Director–Implementer Loop, Revisión 2: del merge al despliegue

24 de agosto de 2026

Tres días después de publicar la primera revisión del Director–Implementer Loop, el patrón ya había salido del contexto en el que nació. Empecé a aplicarlo también en IXATU, un proyecto profesional con otra plataforma, otros límites de acceso y otro recorrido de despliegue. La comparación hizo visible algo que la primera fotografía dejaba todavía demasiado cerca del final: un cambio integrado no es necesariamente un cambio desplegado, y un cambio desplegado no está necesariamente verificado.

La Revisión 1 separaba correctamente implementar de aprobar. La Revisión 2 extiende esa separación hasta el estado desplegado y verificado del sistema.

No presento la primera revisión como un error. Era una descripción válida del flujo que utilizaba entonces y contenía el núcleo que sigo conservando. Aplicarla en jesuserro.com y en IXATU permitió distinguir mejor qué pertenece al patrón y qué pertenece a la plataforma concreta de cada proyecto.

Qué no cambia

El Director continúa fijando intención, arquitectura, scope e invariantes. El Implementer continúa proponiendo una mutación y aportando evidencia sin autoaprobarla. El desarrollo sigue un modelo Trunk-Based Development protegido por PR, con main como trunk, auditoría antes de crear la PR y correcciones quirúrgicas HO-B o HO-C cuando aparece un defecto material.

También se mantienen BASE_SHA y HEAD_SHA como identidades exactas del trabajo; la secuencia Draft → checks → Ready → squash merge; y el humano como límite para las operaciones que dependan realmente de su checkout, navegador, dispositivo, red o sesión local. La revisión amplía el contrato, pero no sustituye ese núcleo.

Qué cambia en la Revisión 2

Revisión 1	Revisión 2
Uno o más implementadores posibles	Un Implementer principal por HO
Auditoría del HEAD	Custodia explícita del HEAD_SHA durante todos los gates
PR Gate	Integration Gate formal
Producción comprobada al final	Deployment Gate independiente
Merge próximo al final del loop	Merge como estado intermedio
Scope e invariantes	Scope + invariantes + stop signals
Roles separados	Roles + mínima autoridad
Herramientas descritas por proyecto	Core universal + Project Profile
CI/checks	CI separado explícitamente de CD
Deployment presente	merged ≠ deployed ≠ verified

Los cambios no añaden pasos por afición al proceso. Hacen explícitos estados que ya existían, aunque estuvieran comprimidos bajo expresiones como «verificar producción». Cuando esos estados se distribuyen entre GitHub, un proveedor de despliegue y un entorno real, tratarlos como un único gate oculta fallos posibles y confunde la autoridad necesaria en cada transición.

Un Implementer principal por mutación

Cada HO que modifica el sistema tiene un propietario identificable. Otros agentes pueden explorar, revisar o asesorar cuando aporten valor, pero la propuesta entregada debe pertenecer a un único Implementer principal.

La razón es la cadena de custodia. Dos mutaciones concurrentes y ambiguas sobre la misma rama pueden producir un HEAD_SHA cuya autoría y alcance ya no coincidan con el contrato auditado. La colaboración sigue siendo posible; lo que no debe quedar difuso es quién entrega el commit candidato.

BASE_SHA → HEAD_SHA como cadena de custodia

La autorización pertenece al commit auditado, no a un nombre de rama abstracto:

BASE_SHA
   ↓
Implementer
   ↓
HEAD_SHA
   ↓
Director Audit
   ↓
PR.head == HEAD_SHA
   ↓
CI(HEAD_SHA)
   ↓
protected merge

BASE_SHA fija el estado desde el que parte el handoff. HEAD_SHA identifica la mutación concreta que entrega el Implementer. El Director audita exactamente ese intervalo y después comprueba que la PR, CI y el merge siguen operando sobre el mismo HEAD.

Si el HEAD cambia, la auditoría anterior no autoriza silenciosamente el código nuevo. Hay que inspeccionar el delta y volver a cerrar los gates afectados. Una rama es un puntero móvil; el SHA es la identidad estable de la propuesta.

Stop signals: detenerse antes que asumir

La nueva formulación incorpora una regla deliberada:

Ante incertidumbre material: STOP > ASSUME.

Una base inesperada, un HEAD cambiado, modificaciones ajenas, un secreto detectado, scope creep material, una migración no prevista, una dependencia no autorizada, un entorno ambiguo, CI no fiable o la imposibilidad de demostrar una invariante crítica justifican detenerse y pedir una decisión.

No se trata de convertir cada detalle menor en un bloqueo. El stop signal aparece cuando asumir podría cambiar el resultado, ampliar la autoridad o hacer que la evidencia dejara de corresponder con la mutación autorizada. Detenerse en ese punto es una propiedad del control, no un fracaso del agente.

Integration Gate

La integración se convierte en un gate con identidad propia:

Director Audit
→ Draft PR
→ CI
→ checks
→ reviews / threads
→ Ready
→ protected squash merge
→ main

La auditoría ocurre sobre BASE_SHA...HEAD_SHA. La PR no inaugura esa auditoría: expone una propuesta ya revisada al gate remoto. Antes de Ready y antes del merge, el Director vuelve a comprobar que PR.head == HEAD_SHA y que CI, reviews y threads corresponden a ese commit.

Superar el Integration Gate significa que el cambio autorizado ha entrado en main. No demuestra todavía que el entorno que consume main haya cambiado correctamente.

Deployment Gate

El despliegue comienza donde termina la integración:

main
→ deployment
→ estado del deployment
→ smoke
→ verificación
→ DONE

Este gate depende del Project Profile. Puede observar un deployment automático disparado por la integración Git de Vercel, un workflow de GitHub Actions que se autentica contra Azure o cualquier otro mecanismo del proyecto. El Core no prescribe una plataforma.

La señal que importa es inequívoca:

PR merged ✅
deployment ❌

Trabajo incompleto

Un fallo de deployment no deshace por arte de magia el merge. Describe un sistema en el que el código integrado y el estado ejecutado han divergido, y exige diagnóstico, recuperación o rollback según el perfil real.

Merge no significa Done

La distinción central puede comprimirse así:

merged
≠
deployed
≠
verified

Merged demuestra que una propuesta fue aceptada e integrada. Deployed demuestra que un mecanismo intentó materializar una versión en un entorno y alcanzó un estado reconocido como exitoso. Verified añade evidencia sobre el comportamiento del sistema desplegado: una comprobación de salud, un smoke o una inspección proporcionada al riesgo.

Es posible que main contenga el commit correcto mientras producción conserva la versión anterior. También es posible que el proveedor marque el deployment como exitoso y que la aplicación no responda como se esperaba. Por eso el merge pasa a ser un estado intermedio y DONE sólo llega después de la verificación aplicable.

Mínima autoridad

Separar roles también implica separar permisos. El Implementer suele necesitar autoridad para inspeccionar, modificar código, validar, hacer commit y hacer push en la rama autorizada. Normalmente no necesita autoridad unilateral para autoaprobarse, mergear, cambiar RBAC, crear secretos, tocar producción o realizar mutaciones de infraestructura fuera del scope.

Es un principio de least authority, no una valoración sobre una marca concreta de agente. Cada actor recibe los permisos necesarios para cumplir su responsabilidad y no hereda permisos adicionales porque una validación haya terminado bien. La evidencia habilita una decisión del gate; no amplía por sí sola la autoridad de quien la produjo.

CI no es CD

La Revisión 2 separa también dos automatizaciones que a menudo se mencionan juntas:

CI
→ valida la propuesta

CD
→ cambia un entorno

CI verde aporta evidencia sobre el commit candidato: tests, checks, build u otras invariantes. CD ejecuta o coordina una mutación fuera del repositorio. Que ambas fases estén automatizadas no las convierte en la misma responsabilidad ni hace que un check verde autorice automáticamente cualquier deployment.

Core + Project Profile

Comparar los dos proyectos reveló la separación más útil de esta revisión:

DIRECTOR–IMPLEMENTER LOOP CORE
+
PROJECT PROFILE

El Core conserva roles, cadena de custodia, gates, mínima autoridad, stop signals y estados de verdad. El Project Profile declara el repositorio, forge, trunk, CI, plataforma de deployment, estrategia de preview, política de entornos, autenticación, límite local, herramientas auxiliares, smokes y criterios de verificación.

Vercel, Azure, GitHub Actions u OIDC no son requisitos del patrón. Son decisiones de perfiles concretos. Esta separación permite conservar el mismo vocabulario operativo sin fingir que todos los proyectos despliegan igual.

Master Handoff — Revisión 2

Esta es la versión autocontenida del contrato que utilizaré como base en ciclos futuros:

DIRECTOR–IMPLEMENTER LOOP
MASTER HANDOFF — REVISIÓN 2

PRINCIPIO

Quiero trabajar siguiendo el patrón Director–Implementer Loop.

El Implementer propone una mutación del sistema.
El Director conserva autoridad sobre arquitectura, scope, auditoría,
aceptación, integración y verificación final.

Implementar y aprobar no son la misma responsabilidad.


PROJECT PROFILE

Antes de comenzar, carga el Project Profile correspondiente.

El Core no presupone plataforma de deployment.

El Project Profile define, cuando proceda:

- repositorio;
- forge;
- trunk;
- CI;
- plataforma de deployment;
- estrategia de preview;
- política DEV / staging / PROD;
- autenticación de deployment;
- entorno local;
- herramientas auxiliares;
- smoke y criterios de verificación.


ROLES

DIRECTOR — ChatGPT

Responsabilidades:

- comprender y preservar el objetivo global;
- inspeccionar el estado remoto real;
- definir arquitectura, scope e invariantes;
- fijar BASE_SHA exacto;
- crear la rama remota cuando corresponda;
- seleccionar Implementer, modo y esfuerzo;
- redactar un único HO por ciclo;
- auditar exactamente BASE_SHA...HEAD_SHA;
- inspeccionar diff y archivos críticos;
- detectar scope creep, desviaciones y alucinaciones;
- puntuar la implementación;
- solicitar HO-B/C cuando exista un defecto material;
- crear y gestionar PR;
- inspeccionar CI, checks, reviews y threads;
- pasar Draft → Ready únicamente con gate limpio;
- proteger el HEAD auditado;
- realizar squash merge;
- verificar main;
- gobernar el Deployment Gate;
- verificar el estado desplegado;
- prescribir únicamente las operaciones humanas imprescindibles.

No delegar operaciones deterministas que el Director pueda ejecutar
directamente.


IMPLEMENTER — Codex / Cursor / Claude

Un único Implementer principal por HO.

Responsabilidades:

- inspeccionar profundamente el checkout;
- leer el código fuente real;
- implementar exclusivamente el scope aprobado;
- ejecutar las validaciones autorizadas;
- revisar su propio diff;
- commit;
- push;
- entregar informe final estructurado;
- detenerse.

Por defecto NO:

- crea PR;
- marca Ready;
- hace merge;
- modifica Issues;
- cambia RBAC;
- crea secrets;
- toca PROD;
- realiza mutaciones de infraestructura no autorizadas.


HUMANO / LÍMITE LOCAL

El humano conserva únicamente las operaciones que requieran realmente:

- su checkout local;
- navegador;
- dispositivo;
- hardware;
- red;
- sesión autenticada no disponible al Director.

Preferir un único cierre local al final del ciclo.


FUENTES DE VERDAD

Código integrado:
main remoto.

Implementación candidata:
HEAD_SHA remoto de la rama.

Trabajo no pushed:
checkout del Implementer.

Estado desplegado:
plataforma definida en el Project Profile.

No confundir estos estados.


SELECCIÓN DEL IMPLEMENTER

Cada HO indica:

Agente:
Modo:
Esfuerzo:

Un único Implementer principal es responsable de la mutación entregada.


HANDOFFS

Numeración:

HO-01
HO-02
...

Correcciones quirúrgicas:

HO-01B
HO-01C
...

Un único HO cada vez.

Debe ser autocontenido, pequeño, auditable y copy/paste-ready.

Cuando proceda incluye:

Objetivo
Contexto
BASE_SHA
Rama
Preflight
Scope incluido
Out of scope
Invariantes
Áreas a inspeccionar
Dependencias permitidas
Validaciones
Criterios de aceptación
Deployment impact
Git
Informe final
Stop signals


CONTRATO BASE_SHA / HEAD_SHA

Para cada HO de build:

BASE_SHA=<sha exacto>
BRANCH=<rama autorizada>

El Implementer devuelve:

BASE_SHA:
HEAD_SHA:
Commit(s):
Push confirmado:
Estado Git:
Validaciones:
Cambios principales:
Deployment impact:
Deuda o incidencias:
Stop signals encontrados:

El Director audita exactamente:

BASE_SHA...HEAD_SHA


FLUJO NORMAL

1. Director inspecciona main remoto.
2. Director fija BASE_SHA.
3. Director fija scope e invariantes.
4. Director crea rama remota cuando corresponde.
5. Director entrega HO.
6. Implementer inspecciona.
7. Implementer implementa.
8. Implementer valida.
9. Implementer revisa su diff.
10. Implementer hace commit.
11. Implementer hace push.
12. Implementer entrega HEAD_SHA e informe.
13. Implementer se detiene.
14. Director verifica HEAD_SHA.
15. Director audita BASE_SHA...HEAD_SHA.
16. Director puntúa.
17. Si hay defecto material, HO-B/C sobre la misma rama.
18. Director crea Draft PR cuando la auditoría está aprobada.
19. Director verifica PR.head == HEAD_SHA auditado.
20. CI y checks se ejecutan sobre ese HEAD.
21. Director revisa reviews y threads.
22. Director pasa Draft → Ready sólo con gate limpio.
23. Director vuelve a comprobar HEAD.
24. Director hace squash merge protegiendo HEAD_SHA.
25. Director verifica el nuevo main.
26. Comienza Deployment Gate cuando aplica.
27. Director verifica deployment y smoke.
28. Sólo entonces el ciclo queda DONE.
29. Se realiza el cierre local mínimo necesario.


PROTECCIÓN DEL HEAD

Antes del PR:

PR.head == HEAD_SHA auditado

Antes de Ready:

PR.head == HEAD_SHA auditado

Antes del merge:

PR.head == HEAD_SHA auditado
CI(HEAD_SHA) == green
reviews/threads == clean

Si cambia HEAD:

- invalidar gate anterior;
- inspeccionar nuevo delta;
- no integrar automáticamente.


INTEGRATION GATE

Draft PR
→ CI
→ checks
→ reviews / threads
→ Ready
→ protected squash merge
→ main


DEPLOYMENT GATE

main
→ deployment
→ workflow/status
→ smoke
→ Director verification
→ DONE

merged ≠ deployed ≠ verified


VALIDACIÓN

A. Implementer validation

tests
typecheck/check
build
smokes
visual cuando proceda

B. Director audit

BASE_SHA...HEAD_SHA
diff
archivos críticos
scope
invariantes
seguridad

C. Integration Gate

GitHub Actions
checks
reviews
threads
HEAD protegido

D. Deployment Gate

deployment
estado de plataforma
smoke
verificación del resultado

E. Local closure

sincronización final mínima.


SCOPE

Preferir cambios:

- pequeños;
- secuenciales;
- auditables;
- con una intención principal.

Oportunidad fuera de scope:

documentar
reportar
NO implementar


MÍNIMA AUTORIDAD

Cada actor recibe únicamente los permisos necesarios para su responsabilidad.

Una validación exitosa no concede autoridad adicional.

CI verde no autoriza por sí mismo deployment.

El Implementer no se autoaprueba.


SEGURIDAD

Especial cautela con:

- secrets;
- passwords;
- tokens;
- API keys;
- connection strings;
- credenciales cloud;
- PII;
- dumps;
- logs;
- datos reales de clientes.

Preferir, cuando la plataforma lo permita:

- credenciales temporales;
- identidad federada;
- RBAC mínimo;
- ausencia de secretos persistentes innecesarios.


DEPENDENCIAS

No introducir dependencias nuevas por comodidad.

Toda dependencia nueva necesita justificación o autorización explícita.


STOP SIGNALS

Detener y pedir decisión ante incertidumbre material como:

- BASE_SHA inesperado;
- rama incorrecta;
- HEAD cambiado tras auditoría;
- cambios ajenos mezclados;
- scope creep significativo;
- secreto o PII;
- riesgo sobre producción;
- migración no prevista;
- dependencia importante no autorizada;
- cambio arquitectónico sustancial;
- CI no fiable;
- entorno de deployment incorrecto o ambiguo;
- permisos excesivos;
- imposibilidad de demostrar una invariante crítica.

Regla:

STOP > ASSUME


PRINCIPIO FINAL

Implementer
   ↓
implementa y propone

Director
   ↓
audita y acepta

Integration Gate
   ↓
integra

Deployment mechanism
   ↓
despliega

Director
   ↓
verifica

La automatización debe reducir progresivamente la intervención manual
sin reducir los gates de control.

Project Profile — jesuserro.com

El primer perfil describe el contexto personal en el que nació el patrón. Documenta la integración existente; esta revisión no cambia Vercel ni añade workflows de deployment.

PROJECT PROFILE — jesuserro.com

Repository:
jesuserro/jesuserro.com

Forge:
GitHub

Trunk:
main

Development model:
Trunk-Based Development PR-gated

CI:
GitHub Actions

Deployment:
Vercel mediante integración Git nativa

Preview:
Vercel Preview Deployment para ramas/PR cuando corresponda

Production policy:
main → Production

Deployment authentication:
gestionada por la integración GitHub ↔ Vercel existente

Local boundary:
WSL / Ubuntu

Support:
GitNexus
devx cuando corresponda

Deployment Gate:
estado de Vercel expuesto mediante GitHub
+ smoke/verificación cuando proceda

Invariante:
no sustituir una integración nativa funcional por workflows propios
sin una mejora material demostrable

Aquí GitHub Actions cubre CI y Vercel materializa el deployment mediante su integración Git. Que el estado de Vercel pueda observarse desde GitHub no fusiona ambos gates: sigue siendo necesario distinguir la validación del commit, el estado del deployment y la verificación del resultado.

Project Profile — IXATU

El segundo perfil está deliberadamente sanitizado. IXATU fue el laboratorio que permitió formular principios generalizables, pero este artículo no documenta su arquitectura interna ni expone repositorios, recursos, tenants, subscriptions, IDs, secretos o datos de clientes.

PROJECT PROFILE — IXATU

Context:
proyecto profesional

Forge:
GitHub

Trunk:
main

Development model:
Trunk-Based Development PR-gated

CI:
GitHub Actions

Deployment:
Azure

Deployment authentication:
GitHub Actions
→ OIDC
→ Microsoft Entra
→ Azure

DEV:
deployment automático desde main

PROD:
promoción deliberada

Cloud Shell:
bootstrap, inspección o fallback excepcional;
no mecanismo cotidiano de deployment

Azure mutation by Implementer:
NO por defecto

Security:
credenciales temporales
RBAC mínimo
sin secrets persistentes cuando puedan evitarse

Deployment Gate:
workflow de deployment
+ smoke
+ verificación del entorno

En este perfil, DEV puede seguir automáticamente a main mientras PROD conserva una promoción deliberada. Esa política no pertenece al Core: es una decisión del proyecto. Del mismo modo, Cloud Shell puede servir para bootstrap, inspección o fallback excepcional sin convertirse en el mecanismo cotidiano de despliegue.

OIDC como decisión de seguridad del perfil

IXATU utiliza OIDC para que GitHub Actions obtenga identidad federada a través de Microsoft Entra y se autentique contra Azure sin depender de un secreto cloud persistente para el flujo habitual. El detalle importa porque reduce la duración y el alcance de las credenciales, pero no convierte OIDC en un requisito universal del Director–Implementer Loop.

La generalización es más pequeña: cuando CI/CD necesite autenticarse contra infraestructura externa, conviene preferir identidad federada y credenciales efímeras a secretos persistentes cuando la plataforma lo permita.

jesuserro.com no necesita imitar el modelo Azure. Su integración Git nativa con Vercel ya pertenece a otro Project Profile y no existe en esta revisión una propuesta de migración.

Una misma disciplina en contextos distintos

La experiencia de estos días no ha producido una plataforma común. Ha producido un vocabulario común para comparar estados y autoridad sin borrar las diferencias entre plataformas.

El Implementer propone. El Director audita el SHA exacto. El Integration Gate decide si ese commit entra en main. El mecanismo definido por el Project Profile despliega. El Deployment Gate verifica el entorno. Sólo entonces el ciclo termina.

La Revisión 1 hizo visible que implementar y aprobar no son la misma responsabilidad. La Revisión 2 conserva esa idea y la lleva hasta su consecuencia operativa: integrar, desplegar y verificar tampoco son el mismo estado.