@imolko/ultra-agent 0.1.0-beta

package/docs/adr/foundational/A-037-formalizacion-taxonomia-labels.md

@@ -0,0 +1,98 @@
+# A-037: Formalización de la taxonomía de labels del issue tracker
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-17
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+Las labels del issue tracker describen el trabajo. Cada label responde exactamente una pregunta, en un namespace con `::`.
+
+Sin una taxonomía formal, esa disciplina se pierde: las labels se acumulan sueltas (una pregunta real sin namespace) u huérfanas (nombran un entregable o un sistema, no una pregunta sobre el trabajo), y el ciclo de vida queda con estados sin label o labels que funden dos preguntas ("¿está listo?" y "¿quién lo ejecuta?") — una máquina no determinista.
+
+La ortogonalidad ([A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md)) fija ese criterio para las labels de wayfinding; las demás dimensiones lo requieren igual.
+
+## Decisión
+
+Formalizar la taxonomía como **seis dimensiones ortogonales**. Cada label responde exactamente una pregunta y va namespaced con `::`.
+
+### Las seis dimensiones
+
+| Dimensión | Pregunta | Valores |
+|-----------|----------|---------|
+| `type::` | ¿qué clase de trabajo? | `bug`, `enhancement`, `idea` |
+| `candy::` | ¿cuánto pesa? | `1`, `2`, `4`, `8` |
+| `exec::` | ¿quién lo ejecuta? | `AFK`, `HITL` |
+| `state::` | ¿en qué fase está? | `needs-info`, `ready`, `in-development`, `completed`, `approved`, `rejected`, `wontfix` |
+| `priority::` | ¿qué urgencia? | `hot`, `warm` |
+| `wayfinder::` | ¿qué artefacto de planificación? | los define [A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md) |
+
+### Reglas de gobierno
+
+1. **Una pregunta por dimensión**: una label responde exactamente una pregunta; ninguna label carga dos significados.
+2. **La ausencia es el estado por defecto**, nunca una label explícita: sin `state::` = sin ingesta; sin `candy::` = `?` (no estimable → wayfinding, [A-035](./A-035-captura-ideas-reanclaje-candies.md)); sin `priority::` = backlog. `candy::16` es vocabulario verbal ("partir"), nunca una label: un issue de 16 debe partirse o ir a wayfinding, no quedarse.
+3. **Un issue es un work item**: las labels describen el trabajo, nunca el entregable. Por eso `documentation` no es un `type::` (la documentación es un *output* que vive en los READMEs de `domain/`, [A-031](./A-031-ubiquitous-language.md) y [A-032](./A-032-domain-artifact-documentation-format.md)) y `system::*` no es una dimensión (el sistema externo ya lo nombra la feature o el título).
+4. **`wayfinder::*` sigue el principio de ortogonalidad** ([A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md)).
+5. **open/closed nativo solo en los terminales**: `state::approved` (verificado → despliegue) y `state::wontfix` cierran el issue; todo otro estado lo deja abierto.
+
+### La máquina de estados
+
+El ciclo de vida es **una sola máquina** (no dos): la **ingesta** — categorizar, verificar, escribir el brief — escribe la región de entrada, la **implementación** ([A-039](./A-039-pipeline-ship-issues-hijos-spec.md)) escribe la de ejecución, y `state::ready` es el puente — despojado de "quién" (eso es `exec::`).
+
+- Sin label = sin ingesta (el estado por defecto, no una label).
+- `state::needs-info`: esperando al reporter.
+- `state::ready`: especificado, en cola para ser tomado; el modo lo da `exec::AFK`/`exec::HITL`.
+- `state::in-development` (antes `developer`): en construcción.
+- `state::completed`: desarrollo terminado, entregado a verificación (la verificación es el intervalo sin label hasta `approved`/`rejected`; `testing` desaparece).
+- `state::approved`: verificado → despliegue → cierra el issue.
+- `state::rejected`: falló la verificación → vuelve a `in-development`.
+- `state::wontfix`: no se hará → cierra el issue.
+
+### Migración
+
+| Antes | Después |
+|-------|---------|
+| `AFK` / `HITL` | `exec::AFK` / `exec::HITL` |
+| `ready-for-agent` | `state::ready` (el "quién" pasa a `exec::`) |
+| `developer` | `state::in-development` |
+| `approved` / `completed` / `rejected` | `state::approved` / `state::completed` / `state::rejected` |
+| `hot` / `warm` | `priority::hot` / `priority::warm` |
+| — | `state::needs-info`, `state::wontfix` (nuevas) |
+| `testing` | — (retirada; la verificación es el intervalo sin label) |
+| `ready-for-human` | — (nunca fue una label: es `state::ready` + `exec::HITL`) |
+| `needs-triage` | — (nunca fue una label: es la ausencia de `state::`) |
+| `system::*` | — (retirada) |
+| `documentation` / `MR` | — (retiradas) |
+| `type::*`, `candy::*`, `wayfinder::*` | sin cambios |
+
+### Quién escribe cada dimensión
+
+| Dimensión | Quién la escribe |
+|-----------|------------------|
+| `type::` | la ingesta (bug/enhancement) y la captura de ideas (idea, [A-035](./A-035-captura-ideas-reanclaje-candies.md)) |
+| `candy::` | la captura de ideas ([A-035](./A-035-captura-ideas-reanclaje-candies.md)) y la reunión semanal (re-estimación, [A-035](./A-035-captura-ideas-reanclaje-candies.md)) |
+| `exec::` | la ingesta, el troceado ([A-039](./A-039-pipeline-ship-issues-hijos-spec.md)) y wayfinding (que reutiliza, [A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md)) |
+| `state::` | la ingesta y la implementación ([A-039](./A-039-pipeline-ship-issues-hijos-spec.md)) |
+| `priority::` | la reunión semanal ([A-035](./A-035-captura-ideas-reanclaje-candies.md)) |
+| `wayfinder::` | wayfinding ([A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md)) |
+
+La maquinaria de cada rol vive en el paquete `@imolko/ultra-agent` ([A-034](./A-034-canonical-skill-set.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Etiquetado determinista**: cada issue lleva exactamente un conjunto bien formado de labels; el estado de un issue se deduce de sus labels sin ambigüedad.
+- **Ortogonalidad real**: `state::` y `exec::` quedan separados — `ready-for-agent` deja de fundir "¿está listo?" con "¿quién?".
+- **Un patrón consistente**: la ausencia como default rige las tres dimensiones con estado por defecto (sin ingesta, `?`, backlog).
+- **Traje limpio**: las labels describen trabajo, no entregables (`documentation`) ni sistemas externos (`system::*`).
+
+### Negativas
+
+- **Migración mecánica**: renombrar/añadir/retirar labels en el issue tracker y re-etiquetar los issues existentes que las llevan.
+- **Pérdida de `testing`**: la fase de verificación deja de ser una label; si el equipo necesita filtrar "en verificación", deberá reintroducirla.
+- **`ready` exige dos labels**: ahora el modo es `state::ready` + `exec::AFK`/`exec::HITL`, donde antes bastaba una sola; es el precio de la ortogonalidad.

package/docs/adr/foundational/A-038-issues-referencian-skills-nombre.md

@@ -0,0 +1,54 @@
+# A-038: Los issues referencian los skills relevantes por nombre
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-19
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+El agente descubre los skills por la `description` de cada `SKILL.md` ([A-034](./A-034-canonical-skill-set.md)). Cuando un issue pide "generar un artefacto de dominio" o "implementar con red-green-refactor" sin nombrar el skill, el agente debe inferir cuál usar. Esto es frágil:
+
+- Si la descripción del skill no incluye las palabras exactas del issue, el agente no lo descubre.
+- El agente pierde tiempo intentando adivinar qué herramienta usar.
+
+## Decisión
+
+Todo issue que un agente consume documenta el skill relevante por su nombre exacto como primera instrucción de la sección `# Skill recomendado`, que define [A-042](./A-042-formato-documentos-issue-tracker.md):
+
+```markdown
+# Skill recomendado
+
+Para comenzar, usa /skill:<nombre> con el siguiente JSON de entrada:
+
+...
+```
+
+### Reglas
+
+| Regla | Descripción |
+|-------|-------------|
+| Referencia explícita | Usar `/skill:<nombre>` con el nombre exacto del skill — el valor del campo `name` de su `SKILL.md` |
+| Primera instrucción | La referencia al skill debe ser lo primero que el agente lee en `# Skill recomendado` |
+| JSON de entrada | Incluir el JSON completo de entrada cuando el skill lo requiera |
+| Skills encadenados | Si el flujo requiere varios skills, referenciarlos en orden |
+| Skills en el spec padre | El spec padre documenta el flujo de skills como referencia para sus issues hijos |
+
+Los skills disponibles viven en el paquete `@imolko/ultra-agent`, la fuente canónica del conjunto ([A-034](./A-034-canonical-skill-set.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Descubrimiento determinista**: el agente no necesita inferir qué skill usar; el issue se lo dice.
+- **Sin tiempo perdido**: el agente va directo a la herramienta correcta.
+- **Flujo encadenado**: issues que requieren varios skills guían al agente por todo el proceso.
+
+### Negativas
+
+- **Mantenimiento de issues**: al crear issues, hay que recordar incluir la referencia al skill.
+- **Acoplamiento**: si un skill cambia de nombre, los issues deben actualizarse.
+- **Duplicación**: el spec padre y sus issues hijos pueden tener instrucciones redundantes.

package/docs/adr/foundational/A-039-pipeline-ship-issues-hijos-spec.md

@@ -0,0 +1,64 @@
+# A-039: Pipeline ship para implementar los issues hijos de un spec
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-17
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+El ciclo canónico de skills ([A-034](./A-034-canonical-skill-set.md)) produce, desde una idea, un spec; el **troceado** lo parte en issues hijos y la **implementación** los ejecuta. Cada hijo se implementa con contexto mínimo y fresco (un hijo + el spec + el progreso reciente), de modo que el agente no deriva entre issues. La **coreografía** que une el troceado con la implementación y con las fases posteriores — revisar, corregir, abrir el merge request — no tiene dueño: sin un orquestador, los pasos de enlace quedan en la memoria de la persona.
+
+## Decisión
+
+El **pipeline `ship`** encadena la implementación de todos los hijos de un spec con la revisión, la corrección y la apertura del merge request. Un programa determinista es el **orquestador**: decide qué issue sigue y transiciona las labels; los sub-agentes son **trabajadores puros** (issue entra, veredicto sale) y nunca tocan el tracker.
+
+### Arquitectura
+
+1. **El orquestador es determinista y ejecuta la máquina de estados** ([A-037](./A-037-formalizacion-taxonomia-labels.md)): elige el siguiente hijo y transiciona sus labels. El modelo nunca decide qué issue sigue; solo trabaja dentro de cada sub-agente.
+2. **Sub-agentes aislados**: cada fase (implementar, revisar, corregir) corre en un proceso aislado, con contexto fresco. El prompt de cada fase vive en **el payload del paquete** `@imolko/ultra-agent` ([A-052](./A-052-distribucion-metodologia-paquete-versionado.md)) — no en `.pi/agents/` del consumidor ni en el código.
+3. **Disparo**: la persona lo invoca con `npx @imolko/ultra-agent ship --parent-iid <IID>` (el comando vive en el puntero `ship_cmd` de `docs/agents/repo-config.md`, [A-052](./A-052-distribucion-metodologia-paquete-versionado.md)), o el **troceado** lo ofrece al terminar, con el IID del padre ya resuelto.
+
+### El bucle de implementación
+
+```
+loop:
+  hijo = pick_next(padre)          # determinista: desbloqueado y ejecutable en automático
+                                   #   (state::ready + exec::AFK); reclama atómicamente
+  veredicto = run implement(hijo)  # sub-agente: contexto fresco; devuelve {estado, resumen, tests}
+  si veredicto.hecho: mark_done(hijo)   # transiciona a completado + comentario en el padre
+  si no:              gestionar fallo    # lo deja en curso y se detiene
+```
+
+Los estados y sus transiciones los define [A-037](./A-037-formalizacion-taxonomia-labels.md); el orquestador los ejecuta.
+
+### Fases finales
+
+- **Revisar**: un sub-agente revisa el diff completo contra el spec y los ADRs, y reporta hallazgos.
+- **Corregir**: sub-agentes corrigen los hallazgos hasta que los tests queden verdes.
+- **MR**: un solo merge request por spec padre; el pie lleva `Closes:` del padre y de los hijos completados ([A-033](./A-033-estandar-mensajes-commit.md)).
+
+### Terminal de los hijos y del padre
+
+La máquina de estados ([A-037](./A-037-formalizacion-taxonomia-labels.md)) fija las transiciones; este ADR refina su terminal: un hijo se **completa** y se **cierra por el MR** (`Closes:`); `state::approved` queda reservado al **padre**, el único work item terminal, y lo marca el desarrollador al fusionar.
+
+### Recuperación
+
+Al arrancar, el orquestador reinicia cualquier hijo que haya quedado en curso de una ejecución interrumpida a `state::ready` (sin asignar) y lo vuelve a ejecutar en fresco; los trabajadores son sin estado, así que re-ejecutar es seguro.
+
+## Consecuencias
+
+### Positivas
+
+- **Una sola acción** desde el troceado hasta el MR: la persona dispara una vez y el pipeline encadena implementación, revisión, corrección y apertura del MR.
+- **Determinismo conservado**: el orquestador — no el modelo — elige el siguiente hijo y transiciona las labels.
+- **Prompt modular**: cada fase se edita en el payload del paquete, fuera del código y fuera del repositorio consumidor.
+- **Reanudación segura**: la reclamación atómica (asignar y transicionar a en curso) evita la doble recogida y permite reiniciar a mitad del padre.
+
+### Negativas
+
+- **Un programa nuevo que mantener**: el orquestador, los prompts de los sub-agentes y el punto de disparo.
+- **El cierre de cada hijo pasa por el pie del MR**: un hijo completado se cierra por el pie `Closes:`; un pie incorrecto lo deja abierto.

package/docs/adr/foundational/A-040-punteros-configuracion-repo-skills.md

@@ -0,0 +1,44 @@
+# A-040: Punteros de configuración del repositorio para los skills
+
+**Estado**: Reemplazado
+
+**Fecha**: 2026-08-17
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+> Reemplazado por [A-052](./A-052-distribucion-metodologia-paquete-versionado.md): el hub de punteros deja de vivir en `.pi/repo-config.md` y pasa a `docs/agents/repo-config.md`, con un bloque `## Agent skills` en `AGENTS.md`/`CLAUDE.md` como ancla neutral al harness.
+
+## Contexto
+
+El conjunto canónico de skills ([A-034](./A-034-canonical-skill-set.md)) fija el **contrato de adaptación**: mapea las convenciones ajenas a las del repositorio. Ese contrato vive como prosa en A-034, no como un artefacto que el agente pueda leer.
+
+Las ubicaciones que mapea el contrato varían por repositorio y no tienen un hogar único: cada skill que las necesita las **hardcodea** en su cuerpo. Un cambio de carpeta obliga entonces a reescribir cada skill que menciona la ruta, y no existe un solo lugar donde el agente consulte dónde viven las cosas en el repo. La convención Imolko es estable y es el default, pero el coste de una divergencia puntual recae entero sobre los cuerpos de los skills.
+
+## Decisión
+
+Añadir un **fichero de punteros de configuración del repositorio** (`.pi/repo-config.md`) como capa de indirección entre los skills y las ubicaciones que varían por repositorio, más un skill que lo genera:
+
+1. **`.pi/repo-config.md`** registra los punteros que varían por repositorio: `adr_dir`, `domain_dir`, `issue_language`, `tracker_cli` y `ship_cmd` (el comando que dispara el pipeline ship, [A-039](./A-039-pipeline-ship-issues-hijos-spec.md)). El fichero es un **hub de punteros, no un glosario**: no duplica el vocabulario de dominio ([A-031](./A-031-ubiquitous-language.md), [A-032](./A-032-domain-artifact-documentation-format.md)) ni el contenido del registro; solo dice dónde viven las cosas y qué switches usa el repo. Los defaults Imolko viven en el fichero, no aquí.
+2. **Los skills leen los punteros en lugar de hardcodear rutas.** Los que referencian el registro ADR o la capa de dominio usan `adr_dir` y `domain_dir` (con una nota que apunta a `.pi/repo-config.md`). `issue_language`, `tracker_cli` y `ship_cmd` quedan registrados como referencia: los comandos de los cuerpos muestran el default Imolko y el agente adapta según el fichero cuando el repo diverge.
+3. **La ubicación del propio fichero es la única ancla hardcodeada** (`.pi/repo-config.md`): la indirección reduce N rutas hardcodeadas a una. `.pi/skills/` ya es el hogar canónico del conjunto ([A-034](./A-034-canonical-skill-set.md)).
+4. **Un generador de un solo paso** escribe `.pi/repo-config.md` con los defaults Imolko y marca las líneas que cambian si el repo diverge.
+5. **La convención sigue siendo el default.** El registro ADR y sus metadatos ([ADR-0000](../ADR-0000-proceso-y-formato-de-adrs.md), los índices y el gate) fijan la ubicación canónica del registro y no cambian; `.pi/repo-config.md` es la capa que los *skills* leen, no una redefinición de la convención.
+6. **Verificación**: una verificación comprueba que los punteros resuelven (las carpetas, el índice y el script de `ship_cmd` existen) y sale con código 0.
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo punto de cambio**: renombrar una carpeta es editar una línea de `.pi/repo-config.md`, no los cuerpos de los skills.
+- **Contrato de adaptación ejecutable**: A-034 deja de ser solo prosa; el fichero es su cara legible por el agente.
+- **Portabilidad**: copiar el conjunto de skills a otro repo y ejecutar el generador de un solo paso lo adapta sin tocar los cuerpos.
+- **Default explícito y verificable**: los defaults Imolko quedan escritos en un solo lugar y la verificación detecta el desfase.
+
+### Negativas
+
+- **Un artefacto más que mantener**: `.pi/repo-config.md` debe mantenerse sincronizado con la realidad; la verificación mitiga el desfase.
+- **Indirección**: cada skill que necesita una ruta debe leer el fichero; es un salto adicional (barato para el agente, pero real).
+- **Doble fuente parcial**: ADR-0000 (y el gate) fijan la ubicación canónica del registro y el fichero la repite como default de `adr_dir`; si la convención cambia hay que tocar ambos.
+- **Ancla única hardcodeada**: `.pi/repo-config.md` sigue siendo una constante; la reducción es N→1, no N→0.

package/docs/adr/foundational/A-041-estrategia-de-ramas.md

@@ -0,0 +1,45 @@
+# A-041: Estrategia de ramas del repositorio
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-21
+
+**originally**: imolko
+
+**tags**: tooling, despliegue
+
+## Contexto
+
+El uso de las ramas no tiene una decisión que lo gobierne como un todo. [A-033](./A-033-estandar-mensajes-commit.md) fija el commit canónico (el squash del MR) y remite el flujo de ramas a este ADR; [A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md) menciona "fusionar a una rama protegida" para el despliegue. Quedan sin decidir qué ramas existen y su ciclo de vida, cómo se nombran, cuándo se crean y se borran, y dónde vive el código desechable de un spike.
+
+Sin una decisión canónica, la mecánica de ramas deriva hacia canon suelto: el skill `spike` ([A-034](./A-034-canonical-skill-set.md)) improvisa una rama desechable sin que ningún ADR defina qué es ni su relación con `feature/*`.
+
+## Decisión
+
+Gobernar el uso de las ramas con un modelo único de **cuatro clases**: dos longevas y dos efímeras.
+
+### Ramas longevas (protegidas, sin push directo)
+
+- `main` — el estado liberado.
+- `develop` — la línea de integración; recibe las features.
+- `develop → main`: **merge commit `--no-ff`** (o fast-forward), para preservar los SHAs de `develop`.
+
+### Ramas efímeras (se crean para un trabajo y se borran al terminar)
+
+- `feature/*` — una feature o fix. Se fusiona a `develop` con **squash** y la rama de origen se **borra** al fusionar.
+- `spike/*` — código desechable que responde una pregunta de diseño (un spike). **Nunca se fusiona**: su código no llega a `develop` ni a `main`. Por defecto el spike **no se commitea** — solo sobrevive su **veredicto**, capturado en la tarea de implementación. Si el artefacto debe quedar referenciable durante la implementación, se commitea a una rama `spike/*` que se **borra** cuando la decisión queda plegada en el código real.
+
+### Nombrado
+
+- `feature/*` y `spike/*` se nombran con una frase corta en minúsculas y guiones (`feature/saga-transferencias`, `spike/ui-fefo`). El número de work item vive en el footer del commit ([A-033](./A-033-estandar-mensajes-commit.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo flujo para personas y agentes**: la mecánica de ramas se gobierna en un solo lugar, para autores y agentes por igual.
+
+### Negativas
+
+- **Un ADR más que mantener**: ampliar el modelo (por ejemplo, una clase `hotfix/*`) exige editar este ADR.
+- **Disciplina de borrado**: la utilidad de `spike/*` depende de que la rama se borre al plegar la decisión; una rama olvidada es desecho persistente.

package/docs/adr/foundational/A-042-formato-documentos-issue-tracker.md

@@ -0,0 +1,78 @@
+# A-042: Formato de los documentos del issue tracker
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-22
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+El ciclo canónico de skills ([A-034](./A-034-canonical-skill-set.md)) publica varios **tipos de documento** en el issue tracker: ideas, specs, tareas, issues triados y los mapas/tickets de wayfinder. La forma de esos documentos no tiene un hogar único: cada skill que produce uno la lleva en su cuerpo, con su plantilla de secciones y un bloque común de reglas de formato duplicado.
+
+Las labels ya las gobierna [A-037](./A-037-formalizacion-taxonomia-labels.md) y la regla de nombrar el skill como primera instrucción la gobierna [A-038](./A-038-issues-referencian-skills-nombre.md), pero la **forma** no la gobierna nadie: vive como canon suelto en los cuerpos de los skills — el mismo modo de fallo que [A-041](./A-041-estrategia-de-ramas.md) ya gobierna para las ramas.
+
+La consecuencia concreta: el contrato entre el skill que **produce** un spec (o tarea, o idea) y los skills que lo **consumen** (el troceado, la implementación y la revisión) es implícito — vive dentro del cuerpo del productor. Un humano que quiera escribir un spec compatible a mano, o un skill consumidor que deba leerlo, no tiene un solo lugar que defina "qué es un spec".
+
+## Decisión
+
+Gobernar la **estructura** de los documentos del tracker en un único ADR fundacional, separando **estructura** de **oficio**:
+
+- **Estructura (aquí)**: los tipos canónicos de documento, los nombres de sección y su orden, y las reglas de formato (comunes a todas las secciones y específicas de sección). Es el contrato de compatibilidad entre productor y consumidor.
+- **Oficio (en el skill productor)**: la prosa que guía cómo escribir cada sección ("Explica la situación…", "Define el alcance…"). No es requisito de compatibilidad; se queda en el skill.
+
+Los skills **cachean y apuntan**: el productor conserva una copia operativa de su plantilla en contexto (es el paso central), marcada como cache de este ADR, y deja de duplicar el bloque común de formato en favor de un puntero. Los skills consumidores apuntan aquí para conocer la forma que leen.
+
+### Tipos de documento y su estructura
+
+| Documento | Secciones (en orden) |
+|-----------|----------------------|
+| Idea (pre-spec) | `# Skill recomendado`, `# Contexto`, `# Idea`, `# Por qué importa`, `# Hecho se ve como` — más `# Pregunta` si no es estimable |
+| Spec | `# Skill recomendado`, `# Contexto`, `# Alcance`, `# Criterio de cierre`, `# Pruebas recomendadas`, `# Decisiones de implementación`, `# Decisiones de testing`, `# Fuera de alcance`, `# Notas adicionales` |
+| Tarea | `# Skill recomendado`, `# Contexto`, `# Alcance`, `# Criterio de cierre`, `# Pruebas recomendadas`, `# Tarea padre`, `# Bloqueado por` |
+| Issue triado (bug/enhancement) | sin secciones fijas — un brief que declara: objetivo, conceptos de dominio, ADRs que constriñen, seams a testear, criterios de aceptación |
+| Mapa wayfinder | `# Destino`, `# Notas`, `# Decisiones tomadas`, `# Aún sin especificar`, `# Fuera de alcance` |
+| Ticket wayfinder | `# Pregunta`, `# Bloqueado por` |
+
+Hay un vocabulario de secciones recurrente entre tipos: `# Skill recomendado` compartido por idea, spec y tarea; `# Contexto`/`# Alcance`/`# Criterio de cierre`/`# Pruebas recomendadas` compartidos por spec y tarea; `# Bloqueado por` compartido por tarea y ticket; `# Fuera de alcance` compartido por spec y mapa. Esa recurrencia es la señal de que la forma es un contrato compartido, no una preferencia de cada skill.
+
+### Reglas comunes de formato
+
+Una sola copia canónica aquí; los skills las apuntan en lugar de duplicarlas:
+
+- Las secciones son **Header 1** (`# Nombre de sección`).
+- Las secciones van seguidas, delimitadas solo por sus títulos.
+- El título de sección es solo el nombre de la sección.
+- El texto es texto plano.
+- Todo el texto en el idioma del repo (`issue_language`, [A-052](./A-052-distribucion-metodologia-paquete-versionado.md)).
+- Markup del tracker (`tracker_cli`, [A-052](./A-052-distribucion-metodologia-paquete-versionado.md)).
+
+### Formato por sección
+
+Además de las reglas comunes, `# Criterio de cierre` (compartido por spec y tarea) tiene un requisito de formato propio: una **lista de tareas con checkboxes** del tracker, una por criterio.
+
+Es el único requisito de formato específico de sección; el resto de secciones solo siguen las reglas comunes.
+
+### Qué no posee este ADR
+
+- **Las labels** → [A-037](./A-037-formalizacion-taxonomia-labels.md), incluido el acople entre cada documento y sus labels.
+- **La regla de nombrar el skill como primera instrucción** (`# Skill recomendado`) → [A-038](./A-038-issues-referencian-skills-nombre.md).
+- **Qué skill produce cada documento** → [A-034](./A-034-canonical-skill-set.md) y la fuente canónica del conjunto, el paquete `@imolko/ultra-agent`.
+- **El oficio** de escribir cada sección → el skill productor.
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo contrato**: la forma de cada documento vive en un lugar; productores y consumidores comparten la misma definición de "qué es un spec/tarea/idea".
+- **Elimina la duplicación**: el bloque común de formato deja de repetirse en cada skill; las plantillas pasan de canon suelto a cache marcada.
+- **Escritura a mano posible**: un humano que escribe un spec sin pasar por el skill tiene el ADR como referencia.
+- **Separación estructura/oficio**: cambiar el contrato no obliga a reescribir el oficio, y viceversa.
+
+### Negativas
+
+- **Un ADR más que mantener**: cambiar la estructura de un documento exige editar este ADR.
+- **Cache desincronizable**: la copia operativa en cada skill puede quedar desfasada de este ADR si no se actualiza al cambiarlo (mitigado por la disciplina de "marcar como cache").
+- **Indirección**: los skills consumidores dan un salto al ADR para conocer la forma que leen.

package/docs/adr/foundational/A-043-vocabulario-etiquetas-adrs.md

@@ -0,0 +1,42 @@
+# A-043: Vocabulario de etiquetas de los ADRs
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-25
+
+**originally**: imolko
+
+**tags**: tooling
+
+## Contexto
+
+El campo `**tags**` del frontmatter de los ADRs admite de una a tres etiquetas. Alojar el vocabulario aprobado de esas etiquetas en el meta-ADR [ADR-0000](../ADR-0000-proceso-y-formato-de-adrs.md), que define el proceso y el formato, acopla el meta-ADR a una lista de valores que evoluciona con el registro: cada vez que el vocabulario cambia, el meta-ADR queda desactualizado y arrastra ese desfase a todos los repositorios que lo importan. El vocabulario es una decisión metodológica agnóstica al lenguaje; su hogar natural es el tier fundacional, no el meta-ADR.
+
+## Decisión
+
+El vocabulario aprobado de etiquetas vive aquí, en el tier fundacional, como fuente única de los valores que admite el campo `**tags**`. Cada ADR del tier A lleva de **una a tres etiquetas**, separadas por comas, en ASCII y en español:
+
+| Etiqueta | Uso típico |
+|----------|------------|
+| `arquitectura` | Estructura, capas, dependencias, bounded contexts. |
+| `dominio` | Reglas de negocio, modelos, value objects. |
+| `eventos` | Event Sourcing, CloudEvents, emisión de eventos. |
+| `testing` | TDD, criterios de test, reportes de tests. |
+| `configuracion` | Settings, contratos de configuración. |
+| `despliegue` | Helm, CI/CD, imágenes Docker, entornos. |
+| `agentes` | Colaboradores LLM, bloques de prompt. |
+| `tooling` | Herramientas del flujo de trabajo (gate, scripts, generadores). |
+
+El campo `**tags**` en sí — su obligatoriedad y su forma — lo define [ADR-0000](../ADR-0000-proceso-y-formato-de-adrs.md); este ADR posee los valores y su semántica. Los tiers T, P y G pueden referenciar este ADR cuando adopten etiquetas.
+
+## Consecuencias
+
+### Positivas
+
+- **Una sola fuente**: ampliar o redefinir el vocabulario es editar este ADR, sin tocar el meta-ADR.
+- **Meta-ADR desacoplado**: ADR-0000 apunta aquí en lugar de contener la lista.
+
+### Negativas
+
+- **Vocabulario acotado**: limitar las etiquetas a ocho valores obliga a mapear cada decisión al vocabulario existente; ampliarlo requiere modificar este ADR.
+- **Sin validación automática**: el gate no comprueba que las etiquetas pertenezcan a este vocabulario; la consistencia depende de la revisión.

package/docs/adr/foundational/A-044-composicion-funcional-procesos-operaciones.md

@@ -0,0 +1,44 @@
+# A-044: Composición funcional de procesos y operaciones
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-29
+
+**originally**: imolko
+
+**tags**: arquitectura
+
+## Contexto
+
+Un proceso de negocio — un caso de uso con sus puertos que resuelve un comando o una consulta ([A-002](./A-002-cqrs-semantico.md)) — y una operación de dominio — un método de un value object, entidad o agregado — expresan una secuencia de pasos. Esa secuencia se puede escribir de dos formas:
+
+- **Como composición**: los pasos se encadenan en un pipeline, cada paso es una función y la salida de uno es la entrada del siguiente.
+- **Como ramas**: el cuerpo desvía el flujo con condicionales y bucles en cada situación.
+
+La forma de ramas entierra la secuencia bajo el control de flujo: para entender el proceso hay que leer cada rama, y para combinar dos operaciones hay que cablear a mano el control de flujo de cada una. La forma de composición expresa la secuencia de negocio de un vistazo y hace cada paso verificable por separado.
+
+Sin una decisión canónica, cada artefacto puede elegir entre componer o ramificar, y el estilo se erosiona.
+
+## Decisión
+
+Adoptar la **composición funcional** como estilo para expresar procesos y operaciones de dominio: cada uno se escribe como un pipeline de pasos encadenados, donde cada paso es una función y la salida de un paso es la entrada del siguiente.
+
+- **Un paso, una función**: cada paso del proceso es una función con una responsabilidad.
+- **Sin ramas de control**: el flujo no se desvía con condicionales ni bucles; la secuencia de pasos es el flujo.
+
+Los operadores concretos del pipeline — el mecanismo de encadenado — los provee el tier de lenguaje de cada ecosistema. Este ADR fija el estilo; no duplica los operadores.
+
+## Consecuencias
+
+### Positivas
+
+- **Legibilidad**: el proceso se lee como una secuencia de pasos de negocio, sin rastrear ramas.
+- **Componibilidad**: dos operaciones se combinan encadenando sus pasos; el resultado de una alimenta la siguiente.
+- **Testabilidad**: cada paso es una función aislada, verificable por separado.
+- **Localidad**: modificar un paso no toca el resto del pipeline.
+
+### Negativas
+
+- **Curva de aprendizaje**: quien viene de estilo imperativo debe reaprender a expresar el flujo como composición.
+- **Verbosidad en pasos triviales**: encadenar pasos de una línea puede ser más ceremonioso que una rama simple.
+- **Disciplina**: exige rechazar ramas de control en revisión; sin ella, el estilo se erosiona.

package/docs/adr/foundational/A-045-guardrails-aplicables-no-directrices.md

@@ -0,0 +1,48 @@
+# A-045: Guardrails aplicables, no directrices
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-31
+
+**originally**: albro
+
+**Enriquecido desde**: Medium "ESLint as AI Guardrails: The Rules That Make AI Code Readable" (Alex Brohshtut)
+
+**tags**: agentes, tooling
+
+## Contexto
+
+Los agentes que colaboran en los proyectos de Imolko escriben código de punta a punta. Las instrucciones que reciben — prompts ([A-023](./A-023-composicion-bloques-prompt-agentes.md)), skills ([A-034](./A-034-canonical-skill-set.md)), specs — dependen de su interpretación, y la calidad de la salida queda a merced de esa interpretación.
+
+Persiguiendo la petición, el agente erosiona la forma del código — funciones largas y números mágicos ([A-046](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md)), dependencias implícitas ([A-047](./A-047-dependencias-explicitas-sin-globales-ambientales.md)) — aun cumpliendo la instrucción.
+
+Sin una decisión canónica, cada repositorio decide si confía en directrices o en guardrails, y el cerco se erosiona.
+
+## Decisión
+
+La salida del agente se gobierna con **guardrails aplicables**, no con directrices. Un guardrail es una regla verificable por máquina que el agente no puede eludir; una directriz es una instrucción que el agente puede ignorar. Los guardrails son dos capas de enforcement:
+
+1. **Tests**: fijan el comportamiento esperado ([A-003](./A-003-tdd.md)).
+2. **Linting**: fija la forma y la legibilidad del código ([A-046](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md)).
+
+### Principios
+
+1. **Enforcement sobre persuasión**: la regla se cumple porque el ciclo la verifica, no porque el agente la recuerde.
+2. **Reglas que solo la persona ajusta**: si una regla hace imposible la tarea, el agente se detiene y lo reporta a la persona; la persona decide si ajusta la regla.
+3. **Bucle de retroalimentación**: tras cada edición, el guardrail se ejecuta; si falla, el agente corrige. Tras N fallos sobre el mismo archivo, el agente se detiene y reporta, para prevenir bucles infinitos de corrección.
+4. **Cerco fijo**: la definición de las reglas y el cerco mismo quedan protegidos; el agente trabaja dentro del cerco. La materialización tiene dos capas: las reglas del linter, responsabilidad del tier de lenguaje, y el bucle que las ejecuta en el ciclo de edición del agente, materializado como extensión nativa de pi ([A-049](./A-049-materializacion-bucle-guardrails-extension-nativa-pi.md)).
+
+Las métricas concretas que verifica el linting viven en [A-046](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md). La composición de los prompts sigue siendo [A-023](./A-023-composicion-bloques-prompt-agentes.md); este ADR define el cerco ejecutable alrededor de esa instrucción, no la instrucción en sí. El bucle de retroalimentación se coloca en el ciclo de edición del agente (materializado por [A-049](./A-049-materializacion-bucle-guardrails-extension-nativa-pi.md)) y como gate en la integración continua ([A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Calidad determinista**: el agente refactoriza mientras trabaja para cumplir el guardrail.
+- **Independencia del modelo**: la regla se cumple o el ciclo se detiene, sin depender de la buena voluntad del agente.
+- **Escalable por ecosistema**: cada lenguaje materializa las mismas reglas con su linter; el principio no cambia.
+
+### Negativas
+
+- **Rigidez**: un guardrail puede bloquear una tarea legítima; la válvula es el reporte a la persona, no el bypass del agente.
+- **Costo de configuración**: cada ecosistema debe materializar el cerco en su tier de lenguaje.

package/docs/adr/foundational/A-046-metricas-de-forma-y-legibilidad-del-codigo.md

@@ -0,0 +1,50 @@
+# A-046: Métricas de forma y legibilidad del código
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-31
+
+**originally**: albro
+
+**Enriquecido desde**: Medium "ESLint as AI Guardrails: The Rules That Make AI Code Readable" (Alex Brohshtut)
+
+**tags**: arquitectura
+
+## Contexto
+
+Sin límites numéricos, el código — humano o generado por agente — tiende a funciones y archivos que crecen sin control, parámetros posicionales largos y números mágicos. La legibilidad queda como preferencia y se erosiona con cada contribución.
+
+El vocabulario del código ya tiene canon: los verbos de intención ([A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)) y el lenguaje ubicuo ([A-031](./A-031-ubiquitous-language.md)) fijan cómo se nombra. Falta fijar la forma: cuán grande puede ser una función, cuántos parámetros, cuánta complejidad.
+
+Estos límites son agnósticos al lenguaje: el criterio no cambia entre ecosistemas. La herramienta que los verifica es la capa de linting del guardrail ([A-045](./A-045-guardrails-aplicables-no-directrices.md)); la materialización concreta (nombres de reglas, excepciones finas) vive en el tier de lenguaje y en la configuración del repo.
+
+## Decisión
+
+Adoptar límites duros de forma y legibilidad para todo el código:
+
+1. **Máximo 2 parámetros por función**: más de dos se agrupa en un único parámetro compuesto.
+2. **Máximo 50 líneas por función** (cuerpo de la función).
+3. **Máximo 250 líneas por archivo**.
+4. **Sin números mágicos**: los literales numéricos con significado se extraen a constantes nombradas. Quedan exceptuados los valores triviales (0, 1, -1, 2) y los índices de colecciones.
+5. **Complejidad máxima 10** por función (ciclomática o cognitiva, según el ecosistema).
+6. **Profundidad de anidamiento máxima 4**.
+7. **Máximo 20 sentencias por función**.
+8. **Un tipo principal por archivo**.
+9. **Longitud mínima de identificador 2** caracteres.
+10. **Igualdad sin coerciones implícitas**: las comparaciones no aplican coerciones de tipo; el operador concreto de igualdad estricta lo provee el tier de lenguaje.
+
+Cada límite es un piso de refactorización: al alcanzarlo, se extrae un helper ([A-044](./A-044-composicion-funcional-procesos-operaciones.md)) y el nombre de la pieza extraída comunica su intención ([A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Legibilidad predecible**: cualquier función o archivo se entiende de un vistazo.
+- **Refactorización continua**: el límite fuerza extraer helpers en lugar de acumular.
+- **Revisión objetiva**: los límites son verificables por máquina, no discutibles por gusto.
+
+### Negativas
+
+- **Verbosidad en pasos triviales**: extraer un helper para una línea puede parecer ceremonioso.
+- **Migración**: el código existente que excede los límites debe refactorizarse, feature por feature.
+- **Excepciones**: casos legítimos (por ejemplo, un mapeo grande) requieren excepciones explícitas en la configuración del tier de lenguaje.

package/docs/adr/foundational/A-047-dependencias-explicitas-sin-globales-ambientales.md

@@ -0,0 +1,40 @@
+# A-047: Dependencias explícitas: sin globales ambientales
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-31
+
+**originally**: albro
+
+**Enriquecido desde**: Medium "ESLint as AI Guardrails: The Rules That Make AI Code Readable" (Alex Brohshtut)
+
+**tags**: arquitectura
+
+## Contexto
+
+El código que accede a globales ambientales — la consola para loguear, las variables de entorno para configurar — esconde sus dependencias: no se ve qué necesita para funcionar, no se puede sustituir en tests y la configuración queda dispersa.
+
+La configuración ya tiene canon: el contrato de settings es su única fuente ([A-013](./A-013-contrato-settings-unica-fuente-configuracion.md)). El logging no lo tiene: falta fijar que se recibe por inyección, no se toma de la consola.
+
+El artículo de referencia enmarca ambas prácticas como una misma regla: el código no accede a globales ambientales; usa inyección de dependencias. Sin una decisión canónica, cada pieza elige entre tomar sus dependencias del ambiente o recibirlas por inyección, y la visibilidad de las dependencias se erosiona.
+
+## Decisión
+
+El código no accede a globales ambientales de forma ad-hoc. Toda dependencia externa se recibe por inyección:
+
+1. **Logging**: el código usa un logger inyectado (un puerto), no la consola. La elección del logger concreto es del tier de lenguaje.
+2. **Configuración**: el acceso a variables de entorno sigue [A-013](./A-013-contrato-settings-unica-fuente-configuracion.md); este ADR no lo re-decide.
+
+El punto de inyección sigue la anatomía de feature ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)) y el wiring del entry point ([A-027](./A-027-patron-wiring-entry-point.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Dependencias visibles**: la firma de una pieza revela qué necesita.
+- **Testabilidad**: logger y configuración se sustituyen en tests.
+
+### Negativas
+
+- **Ceremonia**: inyectar logger y settings añade un puerto o parámetro en piezas que antes los tomaban del ambiente.
+- **Migración**: el código existente que escribe a la consola debe migrarse (el CLI es el principal afectado).