@imolko/ultra-agent 0.1.0-beta

package/docs/adr/foundational/A-048-cobertura-minima-codigo.md

@@ -0,0 +1,39 @@
+# A-048: Cobertura mínima de código
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-04
+
+**originally**: imolko
+
+**tags**: testing
+
+## Contexto
+
+Sin un piso numérico, la cobertura de código se erosiona en silencio: cada contribución sin test baja el número y la suite verde deja de garantizar que el comportamiento queda verificado.
+
+Los tests ya tienen canon: el ciclo TDD ([A-003](./A-003-tdd.md)) fija qué artefactos se prueban y con qué aserciones. Falta fijar el cuánto: el piso de cobertura que un repositorio debe sostener.
+
+Sin una decisión canónica, cada repositorio fija su propio umbral — o ninguno —, y la cobertura deja de ser una señal comparable entre proyectos.
+
+## Decisión
+
+Todo repositorio de Imolko exige una **cobertura mínima de código del 80% de líneas**, medida sobre el código testeable por la herramienta de cobertura de su ecosistema. La cobertura de líneas es la fracción de líneas que ejercita la suite de tests. El piso se verifica como **gate en la integración continua** ([A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)): por debajo del 80%, el pipeline falla.
+
+La verificación de la cobertura pertenece a la capa de tests del guardrail ([A-045](./A-045-guardrails-aplicables-no-directrices.md)); se mide al correr la suite completa.
+
+Qué artefactos quedan cubiertos lo fija [A-003](./A-003-tdd.md); este ADR fija el cuánto. El alcance de lo medido — qué código cuenta como testeable y qué se excluye (generado, glue de infraestructura, wiring de entrada) — lo define el tier de lenguaje y la configuración del repositorio.
+
+## Consecuencias
+
+### Positivas
+
+- **Señal objetiva**: la cobertura es un número verificable por máquina, no una preferencia.
+- **Sin erosión silenciosa**: bajar del 80% rompe el pipeline; la cobertura no se degrada por goteo.
+- **Comparable entre proyectos**: un mismo piso para todos los repositorios de Imolko.
+
+### Negativas
+
+- **Migración**: el código existente por debajo del 80% debe migrarse, feature por feature.
+- **Juego de cobertura**: tests que ejecutan líneas sin verificar su comportamiento inflan el número; la calidad de la aserción la fija [A-003](./A-003-tdd.md) (aserciones semánticas).
+- **Fricción en código de pega**: el glue de infraestructura y el wiring de entrada presionan el piso; la válvula es la exclusión declarada en la configuración del ecosistema.

package/docs/adr/foundational/A-049-materializacion-bucle-guardrails-extension-nativa-pi.md

@@ -0,0 +1,49 @@
+# A-049: Materialización del bucle de guardrails como extensión nativa del agente pi
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-01
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+[A-045](./A-045-guardrails-aplicables-no-directrices.md) gobierna la salida del agente con guardrails aplicables en dos capas — tests ([A-003](./A-003-tdd.md)) y linting, cuyas métricas fija [A-046](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md) — y exige tres propiedades: (1) bucle de retroalimentación tras cada edición, (2) corte tras N fallos sobre el mismo archivo, (3) cerco sin atajos (sin desactivar reglas en línea ni editar la configuración).
+
+A-045 delega la materialización del cerco al tier de lenguaje, lo que cubre las reglas (la configuración del linter, según A-046) pero no el **bucle** que las ejecuta dentro del ciclo de edición del agente. Ese bucle — cuándo se lintea, qué se reporta, cuándo se corta, qué se protege — no tiene dueño, y sin dueño cada repositorio lo improvisa o no lo materializa.
+
+El agente de codificación canónico es **pi** ([A-030](./A-030-global-development-tooling.md)), así que el bucle se materializa como una extensión nativa de pi (`qa-guardrail`). La alternativa — apoyarse en una herramienta de calidad genérica con `bin`/`args` configurables — abriría un vector de ejecución arbitraria en manos del agente: el cerco solo se autosella si la configuración selecciona y acota, nunca ejecuta.
+
+Por último, cuando el guardrail se introduce en un codebase que ya arrastra violaciones de A-046 (migración en curso, feature por feature), el bucle no debe atribuir al agente las violaciones heredadas: de lo contrario el agente se ahoga en ruido que no creó. La retroalimentación debe ser delta-scoped.
+
+## Decisión
+
+Materializar el bucle de A-045 como una extensión nativa de pi, construida de forma nativa (no sobre `pi-code-quality`) y bajo TDD ([A-003](./A-003-tdd.md)):
+
+1. **Configuración de solo selección** — un archivo de configuración versionado declara qué adaptador whitelisted cubre qué archivos: `tools: [{ id, include, exclude, rootMarkers, enabled? }]`. Sin `bin`, `args` ni `formatter`: la configuración selecciona y acota, nunca ejecuta (cerco).
+2. **Capa de adaptadores** — interfaz uniforme `lint(file) → Violation[]` y registro whitelisted de adaptadores (`eslint` hoy; `ruff`/`pylint` futuros). Carga perezosa: cargar la extensión no requiere ningún linter; un binario ausente produce warning, no fallo de carga.
+3. **Ejecución por adaptador** — el adaptador `eslint` corre in-process (API Node de ESLint, instancia única reutilizada, reconstruida si cambia la configuración); los adaptadores Python futuros invocan su CLI. El runner es agnóstico del mecanismo.
+4. **Retroalimentación delta-scoped** — en `tool_result` de `write`/`edit`, se lintea el archivo y se reporta solo el delta contra una línea base congelada «tal como el agente encontró el archivo» (capturada en `tool_call` antes de la primera edición; vacía para archivos nuevos). El agente solo ve — y solo responde por — las violaciones que introduce.
+5. **Corte en N** — contador consecutivo de deltas-fallo por archivo, N=3, reinicio con delta limpio. Al Nth: bloqueo de `write`/`edit` a ese archivo + mensaje «STOP, reportar a la persona» + notificación a la persona; el desbloqueo es humano (`/qa-guardrail reset <archivo>`).
+6. **Cerco** — lista protegida hardcodeada (no configurable): la definición de reglas (`eslint.config.mjs`), la configuración de la propia extensión (`.pi/qa-guardrail.json`) y su propio código (`.pi/extensions/qa-guardrail/**`). Las directivas de desactivación de reglas se detectan independientemente del linter: las nuevas se bloquean en `tool_call`; las heredadas se listan solo en el barrido (`/qa-guardrail check`).
+7. **Alcance v1** — solo linting, solo el entry `eslint`. Sin formatter.
+
+## Consecuencias
+
+### Positivas
+
+- **Calidad determinista**: la regla se cumple o el bucle se detiene, sin depender del modelo.
+- **Sin vector de ejecución arbitraria**: la configuración no puede invocar binarios arbitrarios; el cerco es autosellante.
+- **«Solo mis cambios»**: la retroalimentación delta-scoped no atribuye al agente violaciones heredadas (humanas o de migración).
+- **Carga sin dependencias**: la extensión carga sin ningún linter; cada adaptador toca su dependencia solo al usarse.
+
+### Negativas
+
+- **Costo de propiedad**: una extensión con un esquema deliberadamente menos flexible que una herramienta genérica de calidad (sin `bin`/`args`, sin formatter).
+- **Migración invisible hasta tocar el archivo**: las violaciones heredadas no se reportan salvo que el archivo se edite (por diseño).
+- **Punto ciego estructural durante la migración**: agravar una función ya-no-conforme no se reporta (la violación ya estaba en la línea base).
+- **Falso positivo por desplazamiento de líneas**: la identidad delta es `(rule, line, column)`, así que un edit que desplace líneas por encima de una violación heredada cambia su `line` y puede reportarla como introducida (un falso delta-fallo que suma al corte N). Es el punto ciego inverso del anterior.
+- **Cerco limitado a `write`/`edit`**: el cerco opera sobre `tool_call` de write/edit, por lo que `bash` queda fuera de su superficie de enforcement; es una limitación estructural del cerco, no una desviación.
+- **`eslint` como peer implícito**: el adaptador in-process hace de eslint un peer en tiempo de ejecución; la extensión no era un paquete distribuible hasta declararlos. Resuelto en [A-052](./A-052-distribucion-metodologia-paquete-versionado.md): el paquete de distribución declara `eslint` como dependencia para que la extensión sea distribuible.

package/docs/adr/foundational/A-050-el-caso-de-uso-pide-al-dominio-no-lee-su-representacion.md

@@ -0,0 +1,50 @@
+# A-050: El caso de uso habla en términos del dominio, no lee ni retorna su representación serializada
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-16
+
+**originally**: imolko
+
+**tags**: arquitectura, dominio
+
+## Contexto
+
+El caso de uso opera con agregados y value objects; la infraestructura, con tablas, filas y mensajes ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)). Para cruzar esa frontera, los artefactos de dominio exponen su representación serializada — primitive, payload, snapshot — y el adaptador es quien la consume para hablar con el driver port. Esa representación es la costura de infraestructura, no el vocabulario del caso de uso.
+
+Cuando el caso de uso lee esa representación para decidir o derivar conceptos, pierde el lenguaje del dominio: compara cadenas (`claim.getPrimitive().status === 'Open'`) o ensambla un agregado leyendo las tripas de otro (`stockMovement.getPrimitive().lines[0]…`). El concepto de negocio queda esparcido y duplicado feature a feature, y el compilador no lo vigila. El grep del árbol muestra el mismo patrón en casi todas las features; en `abrir-reclamo` se manifestó como la comparación del `status`.
+
+## Decisión
+
+El caso de uso obtiene hechos y conceptos del dominio **pidiéndoselos** — invocando consultas, predicados y fábricas del dominio —, nunca **leyendo** la representación serializada del objeto. La representación serializada la consumen el adaptador (para serializar al driver) y los tests (para verificar estado); no es vocabulario del caso de uso.
+
+La lectura serializada en el caso de uso esconde cuatro fugas, cada una con su corrección:
+
+| Fuga | Olor | Corrección |
+|------|------|------------|
+| **Decidir sobre estado** | `claim.getPrimitive().status === 'Open'` | un predicado del dominio: `claim.isOpen()` |
+| **Ensamblar un agregado desde otro** | construir un payload leyendo `movement.getPrimitive()` | una fábrica del dominio: `Claim.open(...)` |
+| **Extraer primitivo para un puerto** | `port.findById(vo.getPrimitive())` | el puerto declara el value object, no el primitivo |
+| **Retornar un primitivo en la salida** | `toOutput` devuelve `ctx.claimId.getPrimitive()` | el `OutputDto` lleva el value object; la traducción a primitivo/wire la hace la frontera (controlador o presentador) |
+
+Simétricamente, el caso de uso también **retorna** en términos del dominio: el `OutputDto` lleva value objects, no primitivos. La traducción del value object a su forma plana (primitivo/wire) la hace la frontera — el controlador o el presentador de la app ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)) —, no el caso de uso.
+
+Cuando el dominio modela un concepto como primitivo — p. ej. `Claim.referenceId` es un `string`, y `ReferenceNotFoundError`/`ClaimAlreadyExistsError` llevan `referenceId: string` —, una consulta del dominio puede retornar ese primitivo: es un *getter de primitivo* ([A-005](./A-005-either-return-custom-methods.md)), y el puerto puede permanecer primitivo. La regla "el puerto declara el value object" aplica cuando el dominio tiene un value object para ese concepto.
+
+La regla es un guardrail ([A-045](./A-045-guardrails-aplicables-no-directrices.md)): la cumple la materialización del tier de lenguaje, no la voluntad del autor. El destino es una regla de lint que prohíbe invocar `getPrimitive`/`getPayload`/`getSnapshot` en los casos de uso; se despliega feature a feature — hoy cubre las features ya migradas (p. ej. `abrir-reclamo`) y, para el resto, la comparación de `status`/`state`/`type`.
+
+Este ADR fija *qué* puede leer y retornar el caso de uso; *qué* retornan los métodos que debe invocar lo fija [A-005](./A-005-either-return-custom-methods.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Conceptos en un solo lugar**: el estado y sus transiciones viven en el dominio; el caso de uso los invoca por nombre, preservando el lenguaje ubicuo ([A-031](./A-031-ubiquitous-language.md)).
+- **Guardrail verificable**: la regla de lint fija la forma; el compilador fija el tipo.
+- **Sin duplicación**: el mismo predicado se escribe una vez en el dominio y se invoca desde cada feature que lo necesita.
+
+### Negativas
+
+- **Más métodos en el dominio**: cada consulta, predicado o fábrica es un método nuevo que hay que ubicar en el dominio y testear.
+- **Migración larga**: el patrón está esparcido en casi todas las features; se refactoriza feature a feature.
+- **Tensión con la API actual**: las fábricas (`*.create(payload)`) y algunos puertos (`findById(string)`) hoy reciben primitivos; eliminarlos exige rediseñarlos antes de poder quitar toda lectura serializada.

package/docs/adr/foundational/A-051-orden-imports-por-distancia.md

@@ -0,0 +1,47 @@
+# A-051: Orden de imports por distancia al archivo
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-28
+
+**originally**: imolko
+
+**tags**: arquitectura, tooling
+
+## Contexto
+
+Cada archivo declara sus imports en el orden en que aparecieron, sin criterio: el paquete externo, el módulo del proyecto y el vecino de carpeta se mezclan en la cabecera. El desorden tiene costos concretos:
+
+- **Lectura**: para saber de qué depende un archivo hay que recorrer toda la cabecera en lugar de leer un bloque.
+- **Ruido en revisión**: reordenar imports a mano produce diffs que ocultan el cambio real.
+- **Dirección de dependencias invisible**: la distancia entre un archivo y lo que importa es la señal más barata de con qué capa está hablando; mezclada, la señal se pierde.
+
+La forma del código ya tiene un canon numérico ([A-046](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md)) y un mecanismo de enforcement ([A-045](./A-045-guardrails-aplicables-no-directrices.md)); falta fijar el orden de los imports como parte de esa forma.
+
+## Decisión
+
+Los imports de un archivo se ordenan en **capas de distancia creciente** desde el archivo:
+
+1. **Librerías externas**: builtins del runtime y paquetes de terceros.
+2. **Paquetes del proyecto**: workspaces y alias del repositorio, más externos que la carpeta que contiene el archivo.
+3. **Imports relativos**: de la carpeta más lejana a la más cercana al archivo.
+
+Dentro de cada capa el orden es **alfabético ascendente**. Entre imports relativos, los de subcarpetas —un salto más lejanos— preceden a los del mismo directorio —los más cercanos al archivo—.
+
+La regla es agnóstica al lenguaje. La verifica la capa de linting ([A-045](./A-045-guardrails-aplicables-no-directrices.md)), es auto-corregible, y su materialización concreta —configuración, nombres de reglas, excepciones— vive en el repositorio. Los **imports de efecto lateral**, aquellos sin especificadores cuyo único propósito es ejecutar el módulo, quedan fuera de la regla: su posición puede ser semánticamente significativa y el ordenador no los mueve.
+
+El código existente que aún no cumple la regla se migra de forma incremental: una línea base en el linting congela las violaciones actuales como deuda visible, mientras el código nuevo ya nace ordenado. Al migrar un archivo, su deuda se elimina.
+
+## Consecuencias
+
+### Positivas
+
+- **Cabecera legible**: los imports se leen en bloques de distancia; el bloque dice de dónde viene el archivo.
+- **Dirección de dependencias visible**: un paquete externo arriba y un vecino de carpeta abajo exponen la capa del archivo sin leer su cuerpo.
+- **Revisión sin ruido**: el orden deja de ser preferencia y el reordenamiento aparece solo cuando cambian las dependencias.
+- **Enforcement barato**: la regla es auto-corregible; el agente ordena en el ciclo de edición y la persona no negocia el orden.
+
+### Negativas
+
+- **Deuda de migración**: los archivos que no cumplen la regla permanecen en la línea base de linting hasta migrarse, uno por uno.
+- **Efecto lateral manual**: los imports que deben ejecutarse primero (polyfills, registro de metadatos) no los cubre la regla; su posición depende de quien los escribe.

package/docs/adr/foundational/A-052-distribucion-metodologia-paquete-versionado.md

@@ -0,0 +1,42 @@
+# A-052: Distribución de la metodología como paquete versionado
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-10-02
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+La metodología ultra —el conjunto canónico de skills ([A-034](./A-034-canonical-skill-set.md)) y el registro ADR de los tiers A, T y P— vive en un único repositorio pero no tiene mecanismo de instalación ni de actualización. Cada proyecto que quiere adoptar la metodología copia los skills y el registro a mano: no hay forma de saber qué versión está usando, ni de incorporar cambios posteriores sin volver a copiar a ciegas.
+
+El formato de los skills ya es el estándar Agent Skills, agnóstico al harness, y pi —el agente canónico ([A-030](./A-030-global-development-tooling.md))— tiene un sistema de paquetes nativo. Pero no existe una decisión que fije *cómo* se distribuye la metodología, *qué* se distribuye y *qué ocurre* cuando un consumidor la modifica o la actualiza. El equipo quiere, además, servir a varios agentes (pi como primario), no a uno solo.
+
+## Decisión
+
+Distribuir la metodología como un **paquete npm versionado por suscripción**: `@imolko/ultra-agent`. El consumidor instala una versión, la actualiza subiendo de versión y nunca edita el contenido canónico.
+
+1. **Modelo de suscripción.** El conjunto canónico es de solo lectura en el repositorio consumidor. El consumidor añade sus propios artefactos —skills de proyecto y ADRs de su tier de proyecto— en ubicaciones que el instalador nunca toca. La regla es **«extender, no editar»**: si el consumidor disiente de una decisión canónica, escribe su propio skill o ADR en su espacio, no modifica el canónico.
+2. **Límite de contenido.** Se distribuye solo la metodología: los tiers A, T y P, el meta-ADR `ADR-0000`, el gate de consistencia, los skills canónicos, las extensiones de pi y el **preset de lint** que materializa las reglas ejecutables del tier A — los guardrails aplicables ([A-045](./A-045-guardrails-aplicables-no-directrices.md)) y las reglas estructurales de costura y errores ([A-053](./A-053-errores-compartidos-entre-features-dos-hogares-por-capa.md), [A-054](./A-054-contrato-costura-driver-port-raw-data-canal-error.md)) —. Los ADRs del tier de proyecto de un consumidor concreto (por ejemplo el tier G de Guarura) no forman parte del paquete.
+3. **Espejo de ADRs.** El instalador copia los tiers A, T y P en el `adr_dir` del consumidor como archivos de solo lectura. La actualización reconcilia el espejo y nunca toca el tier de proyecto ni los READMEs de dominio del consumidor.
+4. **Mecanismo.** Un CLI —`npx @imolko/ultra-agent install | update | status`— materializa el conjunto en las ubicaciones de descubrimiento de cada harness y registra un manifiesto de versión para poder reconciliar después.
+5. **Deriva.** Si el consumidor edita un archivo espejado, `update` falla en voz alta ([A-007](./A-007-data-contract-fail-fast.md)) y solo se resuelve con `--reset`, que respalda antes de sobrescribir. No existe `--keep`: conservar una edición del espejo viola el modelo de solo lectura.
+6. **Punteros neutrales al harness.** Los skills leen los punteros del repositorio desde `docs/agents/repo-config.md`, con un bloque `## Agent skills` en `AGENTS.md`/`CLAUDE.md` como ancla —no desde `.pi/`—. Esto sustituye la ubicación fijada en [A-040](./A-040-punteros-configuracion-repo-skills.md).
+7. **Versionado.** El paquete es una librería ([A-017](./A-017-taxonomia-repositorios-librerias-sistemas.md)): SemVer derivado de los tipos de Conventional Commits ([A-033](./A-033-estandar-mensajes-commit.md)) con canal `-beta`. Los detalles de empaquetado npm (manifiesto `pi`, peers y CLI) viven en el tier TypeScript.
+
+## Consecuencias
+
+### Positivas
+
+- **Instalación y actualización reproducibles**: un comando instala y otro reconcilia; la versión instalada queda registrada en el manifiesto.
+- **Metodología única**: todos los proyectos comparten la misma versión canónica, sin forks privados que divergen.
+- **Agente-agnóstico**: los skills se distribuyen por el estándar Agent Skills; las extensiones de pi son una capa adicional, no un requisito.
+- **Sin pérdidas silenciosas**: la deriva se detecta y se resuelve de forma explícita (A-007).
+
+### Negativas
+
+- **Un instalador que mantener**: el CLI y el manifiesto de versión son artefactos más que evolucionar.
+- **Suscripción rígida**: personalizar un skill canónico exige escribir uno de proyecto, no editarlo —más fricción que un fork libre.
+- **Doble fuente parcial**: el espejo de ADRs del consumidor duplica el registro canónico; la reconciliación mitiga la deriva pero no la elimina.

package/docs/adr/foundational/A-053-errores-compartidos-entre-features-dos-hogares-por-capa.md

@@ -0,0 +1,43 @@
+# A-053: Errores compartidos entre features: dos hogares por capa
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-10-02
+
+**originally**: imolko
+
+**tags**: arquitectura, dominio
+
+## Contexto
+
+Los casos de uso de `features/` producen errores que tienden a duplicarse feature a feature: la misma ausencia o el mismo fallo tecnológico reaparece en cada slice con clases idénticas salvo por el nombre de la feature. Son dos especies distintas:
+
+- **Referencias de dominio**: la ausencia de un agregado en una consulta ("no existe"). [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) ya las clasifica como error de dominio: el puerto de dominio nunca retorna `null`; la ausencia la traduce el adaptador y, en una consulta, se convierte en error de dominio.
+- **Fallos de infraestructura**: producidos en la costura del driver ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md), [A-026](./A-026-infraestructura-compartida.md)) — caída de la base de datos, fallo del generador de identificadores, fallo de publicación de eventos —, ajenos al dominio.
+
+[A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) clasifica cada especie pero no fija su **hogar**. Sin un hogar canónico, el mismo error vive duplicado por feature y su identidad estable se dispersa según el nombre de la feature. La regla se formalizó primero en el tier de proyecto de Guarura (G-015); al ser independiente del dominio, se eleva aquí al tier fundacional.
+
+## Decisión
+
+**Dos especies, dos hogares, por capa.** Un error compartido entre features tiene un único hogar según su capa:
+
+1. **Referencias de dominio** — errores de "no existe"/insuficiencia sobre un agregado del dominio — son **errores de dominio** y viven en el **contexto compartido del dominio** que [A-008](./A-008-bounded-context-decomposition.md) describe (el `shared-kernel`). Su identidad se ancla al **agregado** al que refieren, no a la feature que lo consume.
+2. **Fallos de infraestructura** — caída de base de datos, de bus de eventos, de generador de identificadores y afines — son **errores de la capa de aplicación** y viven en un **catálogo compartido paralelo a los slices de feature** ([A-024](./A-024-features-slices-verticales-portables.md)). Su identidad se ancla a la **preocupación de infraestructura** que los produce.
+
+`shared-infra/<tech>/` y `representations/<protocol>/` **no** son hogares: las features nunca importan `shared-infra/` ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md), [A-026](./A-026-infraestructura-compartida.md)) y un catálogo de errores no es una forma de wire de protocolo ([A-026](./A-026-infraestructura-compartida.md)). El catálogo compartido de errores de infraestructura es un módulo hermano dentro del paquete de features, no una feature: las features lo importan sin violar «una feature nunca importa otra feature» ([A-024](./A-024-features-slices-verticales-portables.md)).
+
+**La identidad del error es contrato.** Cada especie hereda la base de error de su capa (la base de error de dominio o la de caso de uso), y su identidad canónica es estable y no se renumera. La forma concreta de esa identidad —el esquema del identificador, las clases base— es materialización del tier de lenguaje, no parte de esta decisión.
+
+## Consecuencias
+
+### Positivas
+
+- **Un único hogar por especie**: cada error duplicado vive una sola vez; corregirlo lo corrige en todas las features.
+- **Identidad estable**: la identidad del error deja de depender del nombre de la feature y refleja el agregado o la preocupación a la que refiere.
+- **Alineación con A-025/A-008**: las referencias de dominio se consolidan donde [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) las clasifica (error de dominio) y donde [A-008](./A-008-bounded-context-decomposition.md) aloja el vocabulario compartido; los fallos de infraestructura quedan en la capa de aplicación.
+
+### Negativas
+
+- **Dos catálogos que navegar**: hay que distinguir «referencia de dominio» de «fallo de infraestructura» para elegir hogar; confundirlas reintroduce la duplicación.
+- **Migración**: consolidar un error duplicado cambia su identidad; los contratos y las aserciones que la codifican deben migrarse en el mismo cambio.
+- **Excepción acotada a A-024**: el catálogo compartido es un módulo compartido dentro del paquete de features, no una feature; el principio «sin librería compartida de ports» ([A-024](./A-024-features-slices-verticales-portables.md)) sigue intacto porque estos no son ports.

package/docs/adr/foundational/A-054-contrato-costura-driver-port-raw-data-canal-error.md

@@ -0,0 +1,65 @@
+# A-054: Contrato de la costura del driver port: raw data y canal de error
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-10-02
+
+**originally**: imolko
+
+**tags**: arquitectura
+
+## Contexto
+
+El driver port es la costura raw-data entre el adaptador y el driver tecnológico ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)). [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) fija su vocabulario —mementos/snapshots, eventos en formato estándar y DTOs planos, sin errores de dominio, sin tipos tecnológicos, `null` para la ausencia— y dónde se decide cada fallo: los errores de dominio en el adaptador y los tecnológicos en el driver. No fija, en cambio, tres cosas:
+
+1. **Por dónde viaja el fallo tecnológico** una vez que el driver lo detecta. Sin ese canal, el driver tiene tres salidas y ninguna es correcta: tragar el fallo y devolver `null` (colapsa «no existe» con «la base falló», contra [A-007](./A-007-data-contract-fail-fast.md)); lanzar una excepción (contra [A-005](./A-005-either-return-custom-methods.md) y [A-007](./A-007-data-contract-fail-fast.md)); o devolver el error de la feature (el driver port arrastra errores de dominio, contra [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)).
+2. **Hasta dónde llega la regla de raw data**. [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) la enuncia en general pero la costura de escritura no event-shaped quedaba sin regla escrita: los driver ports podían recibir agregados o value objects del dominio en `save(...)`, haciendo cruzar el objeto con comportamiento por la costura.
+3. **La frontera de «raw»**. «Ningún tipo del dominio cruza la costura» se leía como una regla de dirección de imports ([A-001](./A-001-clean-architecture-4-capas.md)), cuando la frontera real es **raw vs. comportamiento**: las formas serializables sin comportamiento (mementos/snapshots, la envolvente estándar de eventos, DTOs planos) sí cruzan —se declaren donde se declaren—; los objetos con comportamiento (agregados, entidades, value objects) y el hecho de dominio sin confirmar (que porta una referencia de clase, no data) no cruzan.
+
+El hogar del error de infraestructura ya existe: [A-053](./A-053-errores-compartidos-entre-features-dos-hogares-por-capa.md) decide que los fallos de infraestructura viven en el catálogo compartido de la capa de aplicación y **los produce el adaptador** al traducir el fallo del driver. Faltaba la mitad de la costura: el canal por el que el driver entrega ese fallo. La regla se formalizó primero en el tier de proyecto de Guarura (G-023); al ser independiente del dominio, se eleva aquí al tier fundacional.
+
+## Decisión
+
+### 1. El raw data cruza la costura en ambas direcciones
+
+El driver port usa raw data en **todo** el cruce, no solo en el retorno. Ningún agregado, entidad ni value object del dominio cruza la costura, ni de salida ni de entrada.
+
+- **Lectura/verificación** — el retorno es la forma raw (memento/snapshot) o `null`; los filtros son DTOs planos, nunca value objects del dominio.
+- **Escritura** — el parámetro es la forma raw que corresponde a la costura: la **envolvente estándar** (eventos en formato estándar, [A-015](./A-015-cloudevents-estandar-eventos.md)) cuando es event-shaped, o el **memento/snapshot del agregado** cuando no lo es. `save(snapshot)` es la forma correcta; `save(aggregate)` no lo es.
+- **Quién produce la forma raw** — el adaptador. En la lectura consume el memento y restaura el agregado; en la escritura produce el memento o la envolvente desde los hechos y la entrega al driver. La versión para concurrencia optimista viaja en el memento o la envolvente, no como estado del agregado.
+- **Qué forma raw toca por agregado** lo decide su estrategia de persistencia; esta decisión no cambia esa elección: fija que, sea cual sea, el objeto con comportamiento no cruza.
+
+### 2. El driver port devuelve el canal de error del ecosistema
+
+Todo método del driver port declara el canal de error del ecosistema en su variante asíncrona, según la naturaleza de la operación ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)): las lecturas y verificaciones retornan el resultado de verificación; las mutaciones, el de ejecución. El tipo concreto del canal es materialización del tier de lenguaje.
+
+### 3. La ausencia sigue siendo `null` en el canal de éxito
+
+`null` no cambia de significado: es la ausencia del dato en el vocabulario raw de la costura. La ausencia viaja en el canal de éxito; el fallo tecnológico, en el canal de error. En una consulta que retorna una colección, la colección vacía no es error. El adaptador decide:
+
+- ausencia → error de dominio (o veredicto negativo);
+- fallo tecnológico → error de infraestructura de la feature ([A-053](./A-053-errores-compartidos-entre-features-dos-hogares-por-capa.md)).
+
+### 4. El error del driver port es genérico, ajeno a la feature
+
+El canal de error del driver port porta el fallo tecnológico en su forma neutra, no la unión de errores de la feature ni un error tecnológico concreto. El driver port conserva así el vocabulario raw de [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md): sin errores de dominio y sin tipos de una tecnología concreta. La infraestructura compartida no importa el catálogo de errores de la feature para reportar un fallo ([A-026](./A-026-infraestructura-compartida.md)).
+
+### 5. El adaptador traduce en ambas direcciones y ensancha el canal
+
+El adaptador es el único lugar de la traducción tipada dominio ↔ raw data ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)): restaura el agregado desde el memento en la lectura, produce el memento/la envolvente en la escritura, y traduce el fallo genérico del driver a la unión de errores de la feature. El error de infraestructura compartido ([A-053](./A-053-errores-compartidos-entre-features-dos-hogares-por-capa.md)) integra la unión de errores de la feature que lo consume.
+
+## Consecuencias
+
+### Positivas
+
+- **Dos causas, dos canales**: «no existe» y «la base falló» dejan de colapsar en un único `null`; el caso de uso no reporta una ausencia de negocio ante una caída de infraestructura ([A-007](./A-007-data-contract-fail-fast.md)).
+- **Sin excepciones ni fallbacks**: el fallo tecnológico viaja como valor del canal del ecosistema ([A-005](./A-005-either-return-custom-methods.md), [A-007](./A-007-data-contract-fail-fast.md)).
+- **Costura raw intacta en todo el cruce**: ni los tipos de dominio de salida ni los de entrada cruzan el driver port; el adaptador es el único traductor.
+- **Regla de escritura explícita**: el caso no event-sourced deja de depender de interpretar [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md); `save(aggregate)` queda marcado como no conforme.
+
+### Negativas
+
+- **Un contrato más que aprender en la costura**: el driver que lee distingue ausencia de fallo; el que escribe, éxito de fallo; y ambos reciben/producen raw data.
+- **Drivers existentes por migrar**: los driver ports que reciben el agregado o un value object no cumplen todavía este contrato; la migración es incremental.
+- **Adaptador más explícito**: cada lectura mapea el fallo del driver a un error de feature y cada escritura produce la forma raw.
+- **Deuda de guardrail**: el lint impone dirección de dependencias y prohíbe los tipos sin especificar en los driver ports, pero no detecta «objeto con comportamiento en la costura» ni «sin canal»; mientras no se añada, la conformidad depende de la revisión.

package/docs/adr/foundational/index.md

@@ -0,0 +1,98 @@
+# ADRs Fundacionales (A-XXX)
+
+Decisiones de arquitectura metodológicas y agnósticas al lenguaje. Aplican a todos los proyectos de Imolko (TypeScript, Python, etc.). El proceso y el formato están documentados en [ADR-0000](../ADR-0000-proceso-y-formato-de-adrs.md); el vocabulario de etiquetas vive en [A-043](./A-043-vocabulario-etiquetas-adrs.md).
+
+Los 51 ADRs se agrupan en seis fases narrativas que cuentan el ciclo de desarrollo de Imolko, desde los conceptos de arquitectura hasta el despliegue de aplicaciones, el flujo de trabajo con agentes y el desarrollo de agentes. A-004, A-021 y A-028 permanecen omitidas intencionalmente.
+
+## Arquitectura
+
+La estructura fundacional del sistema: capas, puertos y drivers, bounded contexts, el lenguaje ubicuo y las taxonomías que organizan casos de uso y repositorios.
+
+| # | Título | Estado | Etiquetas |
+|---|--------|--------|-----------|
+| A-001 | [Clean Architecture con 4 capas](./A-001-clean-architecture-4-capas.md) | Aceptado | arquitectura |
+| A-024 | [Features como slices verticales portables](./A-024-features-slices-verticales-portables.md) | Aceptado | arquitectura |
+| A-025 | [Anatomía y mecánica de una feature: puertos, adaptadores y drivers](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) | Aceptado | arquitectura |
+| A-026 | [Infraestructura compartida (shared-infra)](./A-026-infraestructura-compartida.md) | Aceptado | arquitectura |
+| A-027 | [Patrón de wiring entry-point](./A-027-patron-wiring-entry-point.md) | Aceptado | arquitectura |
+| A-002 | [Separación de comandos y consultas](./A-002-cqrs-semantico.md) | Aceptado | arquitectura |
+| A-008 | [Descomposición en Bounded Contexts](./A-008-bounded-context-decomposition.md) | Aceptado | arquitectura, dominio |
+| A-009 | [Taxonomía de criticidad de casos de uso](./A-009-use-case-taxonomy.md) | Aceptado | arquitectura, dominio |
+| A-017 | [Taxonomía de repositorios: sistemas, librerías y configuración](./A-017-taxonomia-repositorios-librerias-sistemas.md) | Aceptado | arquitectura |
+| A-010 | [Propiedad de la emisión de eventos de dominio](./A-010-propiedad-emision-eventos-dominio.md) | Aceptado | arquitectura, eventos |
+| A-029 | [Verbos de intención para métodos del lado del negocio](./A-029-verbos-intencion-metodos-lado-negocio.md) | Aceptado | dominio |
+| A-031 | [Lenguaje ubicuo](./A-031-ubiquitous-language.md) | Aceptado | dominio, agentes |
+| A-050 | [El caso de uso habla en términos del dominio, no lee ni retorna su representación serializada](./A-050-el-caso-de-uso-pide-al-dominio-no-lee-su-representacion.md) | Aceptado | arquitectura, dominio |
+| A-053 | [Errores compartidos entre features: dos hogares por capa](./A-053-errores-compartidos-entre-features-dos-hogares-por-capa.md) | Aceptado | arquitectura, dominio |
+| A-054 | [Contrato de la costura del driver port: raw data y canal de error](./A-054-contrato-costura-driver-port-raw-data-canal-error.md) | Aceptado | arquitectura |
+
+## Desarrollo y Calidad
+
+Cómo se escribe, se prueba y se completa el código: TDD, convenciones de escritura y criterios de calidad que rigen el ciclo de desarrollo.
+
+| # | Título | Estado | Etiquetas |
+|---|--------|--------|-----------|
+| A-003 | [Desarrollo basado en pruebas (TDD)](./A-003-tdd.md) | Aceptado | testing |
+| A-005 | [Métodos del lado del negocio retornan `Result` (Either)](./A-005-either-return-custom-methods.md) | Aceptado | dominio |
+| A-006 | [Criterios de completitud de artefactos de dominio y features (definition of done)](./A-006-feature-completion-criteria.md) | Aceptado | testing |
+| A-007 | [Contrato de datos: fallo en origen, sin fallbacks silenciosos](./A-007-data-contract-fail-fast.md) | Aceptado | testing |
+| A-011 | [Refactoring con characterization tests](./A-011-characterization-first-refactoring.md) | Aceptado | testing |
+| A-044 | [Composición funcional de procesos y operaciones](./A-044-composicion-funcional-procesos-operaciones.md) | Aceptado | arquitectura |
+| A-046 | [Métricas de forma y legibilidad del código](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md) | Aceptado | arquitectura |
+| A-047 | [Dependencias explícitas: sin globales ambientales](./A-047-dependencias-explicitas-sin-globales-ambientales.md) | Aceptado | arquitectura |
+| A-048 | [Cobertura mínima de código](./A-048-cobertura-minima-codigo.md) | Aceptado | testing |
+| A-051 | [Orden de imports por distancia al archivo](./A-051-orden-imports-por-distancia.md) | Aceptado | arquitectura, tooling |
+
+## Despliegue
+
+Cómo se empaqueta y despliega una aplicación: Helm, configuración, eventos, CI/CD, imágenes Docker y el entorno estandarizado.
+
+| # | Título | Estado | Etiquetas |
+|---|--------|--------|-----------|
+| A-012 | [Helm como mecanismo primario de despliegue para aplicaciones servidor](./A-012-helm-mecanismo-primario-despliegue.md) | Aceptado | despliegue |
+| A-019 | [Convenciones de autoría de Helm charts](./A-019-convenciones-autoria-helm-charts.md) | Aceptado | despliegue |
+| A-013 | [Contrato de settings como única fuente de configuración de la aplicación](./A-013-contrato-settings-unica-fuente-configuracion.md) | Aceptado | configuracion |
+| A-014 | [Generación de artefactos de despliegue desde el contrato de settings](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md) | Aceptado | despliegue, configuracion |
+| A-015 | [CloudEvents como estándar de eventos](./A-015-cloudevents-estandar-eventos.md) | Aceptado | eventos |
+| A-016 | [CI/CD con GitLab: pipeline raíz y pipelines modulares por app](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md) | Aceptado | despliegue, tooling |
+| A-018 | [Prácticas de build de imágenes Docker](./A-018-practicas-build-imagenes-docker.md) | Aceptado | despliegue |
+| A-020 | [Entorno de desarrollo estandarizado con DevContainer](./A-020-entorno-desarrollo-estandarizado-devcontainer.md) | Aceptado | tooling |
+
+## Herramientas
+
+Formatos, estándares y herramientas transversales del flujo de trabajo: el vocabulario de etiquetas de los ADRs, el reporte de tests, el toolchain global, la documentación de artefactos, los mensajes de commit y las ramas.
+
+| # | Título | Estado | Etiquetas |
+|---|--------|--------|-----------|
+| A-043 | [Vocabulario de etiquetas de los ADRs](./A-043-vocabulario-etiquetas-adrs.md) | Aceptado | tooling |
+| A-022 | [Formato de reporte de tests (CTRF)](./A-022-formato-reporte-tests-ctrf.md) | Aceptado | testing, tooling |
+| A-030 | [Herramientas de desarrollo globales](./A-030-global-development-tooling.md) | Aceptado | tooling, agentes |
+| A-032 | [Formato de documentación de artefactos de dominio y features](./A-032-domain-artifact-documentation-format.md) | Aceptado | dominio, tooling |
+| A-033 | [Estándar de mensajes de commit](./A-033-estandar-mensajes-commit.md) | Aceptado | tooling, agentes |
+| A-041 | [Estrategia de ramas del repositorio](./A-041-estrategia-de-ramas.md) | Aceptado | tooling, despliegue |
+
+## Flujo de agentes
+
+El flujo de trabajo del agente de codificación sobre el issue tracker: el conjunto canónico de skills, la convención de referenciarlos por nombre, la captura de ideas, wayfinder, la taxonomía de labels, el pipeline ship, los punteros de configuración del repo y el formato de los documentos.
+
+| # | Título | Estado | Etiquetas |
+|---|--------|--------|-----------|
+| A-034 | [Conjunto canónico de skills del asistente de codificación](./A-034-canonical-skill-set.md) | Aceptado | agentes, tooling |
+| A-038 | [Los issues referencian los skills relevantes por nombre](./A-038-issues-referencian-skills-nombre.md) | Aceptado | agentes, tooling |
+| A-035 | [Captura de ideas y re-anclaje de candies al flujo de agentes](./A-035-captura-ideas-reanclaje-candies.md) | Aceptado | agentes, tooling |
+| A-036 | [Wayfinding y ortogonalidad de labels del issue tracker](./A-036-adopcion-wayfinder-ortogonalidad-labels.md) | Aceptado | agentes, tooling |
+| A-037 | [Formalización de la taxonomía de labels del issue tracker](./A-037-formalizacion-taxonomia-labels.md) | Aceptado | agentes, tooling |
+| A-039 | [Pipeline ship para implementar los issues hijos de un spec](./A-039-pipeline-ship-issues-hijos-spec.md) | Aceptado | agentes, tooling |
+| A-040 | [Punteros de configuración del repositorio para los skills](./A-040-punteros-configuracion-repo-skills.md) | Reemplazado | agentes, tooling |
+| A-042 | [Formato de los documentos del issue tracker](./A-042-formato-documentos-issue-tracker.md) | Aceptado | agentes, tooling |
+| A-045 | [Guardrails aplicables, no directrices](./A-045-guardrails-aplicables-no-directrices.md) | Aceptado | agentes, tooling |
+| A-049 | [Materialización del bucle de guardrails como extensión nativa del agente pi](./A-049-materializacion-bucle-guardrails-extension-nativa-pi.md) | Aceptado | agentes, tooling |
+| A-052 | [Distribución de la metodología como paquete versionado](./A-052-distribucion-metodologia-paquete-versionado.md) | Aceptado | agentes, tooling |
+
+## Desarrollo de agentes
+
+Estándares para construir los colaboradores LLM que un proyecto invoca: la composición de sus prompts en bloques. Aplica solo a los proyectos que desarrollan agentes.
+
+| # | Título | Estado | Etiquetas |
+|---|--------|--------|-----------|
+| A-023 | [Estándar de composición de bloques de prompt para agentes](./A-023-composicion-bloques-prompt-agentes.md) | Aceptado | agentes, tooling |

package/docs/adr/index.md

@@ -0,0 +1,19 @@
+# Architecture Decision Records (ADR)
+
+Registro de decisiones de arquitectura canónico del equipo Imolko. Cubre la metodología ultra en tres tiers — fundacional (agnóstico al lenguaje), TypeScript y Python —. Cada proyecto que adopta la metodología añade su propio tier de proyecto con sus decisiones de dominio; el tier G de Guarura fue un ejemplo de tier de proyecto y no forma parte de la metodología distribuida ([A-052](./foundational/A-052-distribucion-metodologia-paquete-versionado.md)).
+
+El proceso, el formato y las reglas que gobiernan estos ADRs están documentados en [ADR-0000: Proceso y formato de los ADRs](./ADR-0000-proceso-y-formato-de-adrs.md).
+
+## Tiers
+
+Los ADRs de metodología se organizan en tres tiers según su alcance. La jerarquía completa (reglas de referencia, numeración y gate) está en [ADR-0000](./ADR-0000-proceso-y-formato-de-adrs.md).
+
+- **Fundacional (A)** — [`foundational/index.md`](./foundational/index.md): decisiones metodológicas agnósticas al lenguaje (Clean Architecture, TDD, comandos y consultas, DDD).
+- **TypeScript (T)** — [`typescript/index.md`](./typescript/index.md): decisiones específicas del ecosistema TypeScript/Zod/Node.js.
+- **Python (P)** — [`python/index.md`](./python/index.md): decisiones específicas del ecosistema Python (FastAPI, SQLAlchemy, Pydantic).
+
+Cada repositorio consumidor mantiene su propio **tier de proyecto** con sus decisiones de dominio, fuera de los tres tiers de metodología.
+
+## Formato
+
+Cada ADR sigue el formato de Michael Nygard (Contexto, Decisión, Consecuencias) con el frontmatter del proyecto. El detalle completo del formato, la jerarquía, el gate y el ciclo de vida está en [ADR-0000](./ADR-0000-proceso-y-formato-de-adrs.md). El vocabulario de etiquetas vive en [A-043](./foundational/A-043-vocabulario-etiquetas-adrs.md).

package/docs/adr/python/P-001-dependencias-por-feature-fastapi-depends.md

@@ -0,0 +1,63 @@
+# P-001: Dependencias por feature con FastAPI Depends
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-005
+
+**Enriquecido desde**: Cortex ADR 005 — Dependency providers with FastAPI Depends
+
+## Contexto
+
+Cada feature de una API en Python necesita resolver sus dependencias en cada request. Algunas son **compartidas** por todas las features — cliente de IA, estado de sesión, usuario autenticado — y otras son **específicas** de una feature — almacenamiento de objetos, búsqueda vectorial, puertos de un dominio concreto.
+
+Montar esas dependencias a mano en cada handler genera duplicación y ciclos de vida inconsistentes: un endpoint las inicializa en un orden y otro en otro, y no queda clara cuál es la fuente canónica de cada servicio.
+
+## Decisión
+
+Usar el sistema de inyección de dependencias de FastAPI, `Depends()`, con **dos capas**.
+
+### 1. Dependencias conocidas (compartidas)
+
+Una función proveedora única agrupa las dependencias que todas las features comparten. Recibe por `Depends()` cada proveedor individual y retorna un contenedor (un dataclass) con las dependencias ya resueltas:
+
+```python
+def known_deps_provider(
+    ai_client = Depends(ai_client_provider),
+    session_state = Depends(session_state_provider),
+    current_user = Depends(current_user_provider),
+) -> KnownDependencies:
+    return KnownDependencies(
+        ai_client=ai_client,
+        session_state=session_state,
+        current_user=current_user,
+    )
+```
+
+### 2. Dependencias custom (por feature)
+
+Cada feature declara su propia función `*_deps`, que recibe el contenedor de dependencias conocidas y retorna los servicios adicionales que esa feature necesita:
+
+```python
+def generate_blueprint_deps(known: KnownDependencies) -> dict:
+    return {
+        "object_storage": object_storage_service,
+        "vector_search": vector_search_service,
+    }
+```
+
+Ambas capas se inyectan al construir el router y quedan disponibles en el contexto del request.
+
+## Consecuencias
+
+### Positivas
+
+- **Declarativo por feature**: cada feature pide solo lo que necesita; no hay una "sopa global" de dependencias.
+- **Resolución per-request**: FastAPI resuelve la cadena de `Depends()` de forma perezosa en cada request.
+- **Testeable**: ambas capas son funciones que se pueden sustituir en tests.
+
+### Negativas
+
+- **Grafo implícito**: hay que seguir la cadena de `Depends()` para entender el orden de inicialización.
+- **Contenedor único**: agregar una dependencia conocida nueva toca el contenedor compartido y, por lo tanto, a todas las features.

package/docs/adr/python/P-002-inyeccion-token-por-request-sin-persistirlo.md

@@ -0,0 +1,35 @@
+# P-002: Inyección de token por request sin persistirlo
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-003
+
+**Enriquecido desde**: Cortex ADR 003 — Per-request token injection (never stored)
+
+## Contexto
+
+Una API necesita autenticarse contra un servicio externo (por ejemplo, un ACL que resguarda archivos y tareas) usando un token que pertenece a cada tenant. Guardar ese token en variables de entorno o en el contrato de settings acoplaría la aplicación al token de un tenant concreto y crearía un riesgo de seguridad si la aplicación se ve comprometida.
+
+## Decisión
+
+- Los tokens se pasan **por request** mediante una cabecera HTTP dedicada (por ejemplo `X-<Proveedor>-Token`).
+- La aplicación **nunca persiste** el token: crea un cliente acotado al lifetime del request y lo descarta al terminar.
+- Si la cabecera falta, el endpoint responde `401 Unauthorized`.
+- El contrato de settings **excluye explícitamente** cualquier campo de token: las credenciales por tenant no son configuración de la aplicación ([A-013](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)).
+
+Los procesos en background que no tienen contexto HTTP (workers, jobs) siguen el mismo principio, pero usan variables de entorno porque no existe un request al que asociar el token.
+
+## Consecuencias
+
+### Positivas
+
+- **Multi-tenant**: una única instancia puede servir a varios tenants, cada uno con su propio token.
+- **Seguridad**: un proceso comprometido no tiene tokens de larga vida que exfiltrar.
+- **Stateless**: no se necesita afinidad de sesión para almacenar tokens.
+
+### Negativas
+
+- **Carga para el llamador**: cada request debe incluir la cabecera; el gateway o el cliente lo asumen.
+- **Validación diferida**: el token no se valida en el ingreso del request, sino en la primera llamada al servicio externo.