Director–Implementer Loop, Revisión 4.1: GitHub como handoff y localhost como gate humano
La Revisión 4 resolvió una pregunta de ownership:
¿quién construye y quién opera?
R4.1 responde a la pregunta siguiente, la que aparece cuando el patrón se usa de verdad varias veces:
¿cómo se entrega el trabajo entre ambos sin copy/paste, sin polling duplicado y conservando un único gate humano que merezca la pena?
Esta revisión no nace de un diseño de pizarra. Se consolidó dogfoodeando el loop en cambios reales —incluido un frente largo de Reviews canónicas— hasta que el transporte, el preview y el cierre dejaron de ser improvisación.
De R4 a R4.1
R4 dejó la frontera clara:
Implementer builds
Director operatesR4.1 fija el protocolo operativo que ha funcionado:
Implementer
↓
Draft PR + GitHub handoff + localhost
↓
STOP
↓
human acceptance
↓
Director closesLa diferencia no está en quién es el Director. Está en dónde vive el handoff, cuándo sale el Implementer y qué intervención humana se conserva.
GitHub como bus de handoff
Durante un tiempo el cuello de botella no era el código. Era el traslado del Evidence Pack entre chats: copiar, pegar, perder un SHA, confundir un HEAD viejo con uno nuevo.
R4.1 elimina ese gesto. El Implementer publica automáticamente en la Draft PR un comentario marcado:
<!-- jesuserro-director-handoff:v1 -->El envelope lleva type, agent, pr, branch, head_sha, base_sha y status. El Director recupera desde GitHub el handoff correspondiente. El usuario no hace de mensajero.
Ventajas que se notan en cuanto se usa:
- durable;
- ligado a la PR;
- ligado a un
head_shaconcreto; - consultable por el Director sin depender del chat;
- auditable;
- sin copy/paste.
GitHub es transporte y audit trail. No es autoridad editorial ni fuente canónica de datos.
El HEAD es parte del mensaje
Un handoff no es un informe genérico sobre «la PR». Es una afirmación sobre un commit exacto:
handoff(head = A)sólo autoriza decisiones sobre:
PR HEAD = ASi el HEAD pasa a B, el handoff de A queda STALE. No sirve para aprobar B. Esa regla es la misma que el expected-head merge: la evidencia pertenece a una mutación concreta.
STOP significa STOP
El Implementer valida en local, predice el routing de CI que espera, publica el handoff y se detiene.
No espera GitHub Actions. No espera Vercel. No interpreta CI remoto. No hace reruns. No marca Ready. No mergea.
Eso ahorra tokens y elimina un polling redundante: si el Director va a observar el pipeline, no tiene sentido pagar dos veces la misma vigilancia.
expected CI
≠
observed CI
≠
interpreted CILocalhost como gate humano
La intervención humana que merece conservarse no es copiar evidencias, mirar CI, hacer merge ni limpiar ramas.
Es:
ver y comprender el cambio real antes de integrarlo.
Por eso el Implementer deja localhost levantado y describe las superficies relevantes. El usuario puede inspeccionar antes de despertar al Director. En el camino ideal, una sola intervención humana basta:
Implementer STOP
↓
usuario abre localhost
↓
usuario comprueba
↓
“continúa (aprobado visualmente)”
↓
Director audita y cierraSi el usuario escribe sólo continúa, el Director puede recuperar el handoff y pedir el gate visual si todavía falta. Si escribe continúa (aprobado visualmente), eso despierta al Director y deja constancia de aceptación del preview del HEAD entregado.
Un microfix posterior del Director que cambie la UI visible exige nueva revisión. Un arreglo invisible de types/tooling/CI, no.
USER_PREVIEW como pequeña interfaz
El Evidence Pack sigue siendo machine-readable. El mensaje final visible del Implementer es humano y práctico.
Para cada URL:
URL
WHY
CHANGE / PROOF
REVIEW
EXPECTEDY las URLs van en Markdown normal, clicables —nunca encerradas en un bloque de código que obligue a copiar a mano.
Eso convierte el preview en una mini interfaz de aceptación, no en un apéndice opcional.
continúa como handoff humano explícito
No busco eliminar toda intervención. Busco que la intervención que queda sea barata, explícita y significativa.
continúa (aprobado visualmente) es simple:
- despierta al Director;
- documenta que el usuario ha visto el HEAD entregado.
No hace falta un formulario. No hace falta un bot. Hace falta un gesto humano con significado.
R4.2: automatizar más no fue mejor
También se probó despertar al Director con una Task/evento automático.
No lo oculto: el experimento existió y se descartó.
La experiencia no despertó de forma suficientemente fiable, añadió complejidad y podía gastar capacidad de agentes en observar CI —justo el trabajo que R4.1 reserva al Director sin intermediarios opacos.
La conclusión operativa es clara:
una automatización que elimina un gesto barato pero introduce coste, opacidad o pérdida de control no es una mejora.
R4.2 queda como experimento rechazado. El protocolo vigente es R4.1.
CI pertenece al Director
El Director hace triage:
- infra/flaky → rerun dirigido;
- tooling pequeño y localizado → microfix del Director cuando el riesgo está acotado;
- regresión sustantiva → Delta HO al Implementer con HEAD, gate, expected, actual, log y scope exactos.
No se envía «mira a ver qué pasa con CI». Se envía evidencia focal.
Microfix vs vuelta al Implementer
El Director puede corregir cuando el fallo es pequeño, determinista, localizado, sin cambio arquitectónico y sin tocar prosa del usuario.
Si el arreglo exige juicio de implementación o cambia el diseño, vuelve el Implementer. Esa frontera evita tanto el ping-pong inútil como el «ya lo arreglo yo» que diluye ownership.
La PR como registro del proceso
Con R4.1, la Draft PR no es sólo el diff. Puede conservar:
Implementer handoff
Director audit
human acceptance
delta handoff
CI diagnosis
merge decisionNo hace falta volcar conversaciones enteras. Basta con que el rastro operativo quede junto al cambio. Eso es trazabilidad sin teatro.
El loop R4.1 final
Director
↓
HO
Implementer
↓
implementa
↓
valida localmente
↓
Draft PR
↓
Evidence Pack publicado en GitHub
↓
localhost + USER_PREVIEW
↓
STOP
Usuario
↓
inspecciona
↓
“continúa (aprobado visualmente)”
Director
↓
recupera handoff (head_sha = HEAD)
↓
audita
↓
Ready
↓
observa / interpreta CI
↓
expected-head merge
↓
post-merge + cleanup
↓
un único sync localQué queda humano y qué queda automatizado
| Actor | Aporta |
|---|---|
| Implementer | construcción y evidencia local |
| GitHub | transporte y audit trail |
| Usuario | comprensión y aceptación |
| Director | juicio, operación y cierre |
| CI / Vercel | evidencia automática |
El objetivo no es que el humano desaparezca. Es quitar del humano y de los agentes todo lo que no necesita juicio, y conservar el punto donde mirar, entender y decidir sigue aportando valor.
Por qué lo llamo 4.1 y no 5
R4.1 no redefine los roles fundamentales de R4. Refina el transporte y la ergonomía del mismo contrato.
Por eso es una evolución menor en nombre y muy significativa en operación: menos fricción, menos tokens gastados en vigilancia, más claridad sobre qué SHA se aprueba y qué preview se aceptó.
Cierre
La Revisión 1 separó implementar de aprobar. La Revisión 3 llevó el loop hasta una versión verificable. La Revisión 4 separó construcción y operación. R4.1 hace que esa separación se pueda ejecutar todos los días sin pedirle al usuario que haga de cable entre agentes.
Cuando el handoff viaja por GitHub, el Implementer sabe cuándo parar y el humano conserva el único gate que importa —ver el cambio—, el loop deja de ser una teoría de roles y pasa a ser un protocolo que se puede repetir.