Director–Implementer Loop, Revisión 4: evidencia estructurada y CI bajo el Director

5 de septiembre de 2026

La Revisión 1 separó implementar de aprobar. La Revisión 2 distinguió integración, despliegue y verificación. La Revisión 3 extendió la cadena hasta el artefacto verificable, la promoción y el Release Gate.

La Revisión 4 nace de otra fricción más cotidiana: el Implementer estaba haciendo demasiado trabajo operativo después de haber terminado de implementar.

Era habitual que un agente terminara el código, ejecutara sus tests, hiciera push y abriera la PR, pero siguiera consumiendo tiempo y tokens esperando GitHub Actions, consultando estados, interpretando fallos, vigilando Vercel y relatando una secuencia que el Director debía volver a comprobar después.

La nueva regla es sencilla:

El Implementer construye y aporta evidencia. El Director observa, interpreta, decide y cierra.

No es sólo una optimización de coste. Es una separación más limpia de responsabilidades.

El cambio central

Hasta R3, la frontera entre construcción y operación seguía siendo algo difusa en la práctica. El Implementer podía terminar convertido temporalmente en programador, QA operator, observador de CI y operador de GitHub.

R4 fija una frontera explícita:

IMPLEMENTER
───────────
implementación
↓
validación local
↓
self-review del diff
↓
commit + push
↓
Draft PR
↓
Evidence Pack
↓
FIN DE SU TURNO

DIRECTOR
────────
auditoría independiente
↓
observación de CI
↓
interpretación / routing
↓
Vercel / deployment evidence
↓
Ready
↓
expected-head merge
↓
post-merge verification

El Implementer puede conocer qué CI espera provocar, pero no tiene que quedarse esperando a comprobarlo.

Ese matiz es importante:

predecir CI ≠ observar CI ≠ interpretar CI

La predicción forma parte de la evidencia del Implementer. La observación y la interpretación pertenecen al Director.

Nuevo contrato de salida del Implementer

Un trabajo normal queda terminado para el Implementer cuando puede entregar:

• rama dedicada;
• BASE_SHA conocido;
• HEAD_SHA exacto;
• diff revisado;
• validación local proporcional al riesgo;
• commits publicados;
• Draft PR;
• Evidence Pack;
• routing de CI esperado.

No necesita añadir:

"esperaré a CI"
"volveré a comprobar Vercel"
"el deployment sigue pendiente"

El agente sale del loop en ese punto.

Esto evita una duplicación que se había vuelto evidente: si el Director va a tomar la decisión final, no tiene sentido pagar dos veces la misma observación.

Evidence Pack: hechos antes que relato

R4 introduce una superficie explícita de evidencia estructurada.

El problema no era que los implementadores informasen mal. Muchos informes eran excelentes. El problema es que una narración sigue siendo una narración: puede omitir sin querer un archivo, confundir una base local desactualizada o describir como hecho algo que sólo era una expectativa.

El Evidence Pack separa dos capas:

HECHOS GENERADOS
───────────────
branch
base SHA
HEAD SHA
working tree
commits
changed files
áreas afectadas
routing CI esperado
estado canonical disponible

INTERPRETACIÓN
──────────────
decisiones
riesgos
pendientes
motivos

La primera capa debe poder ser generada por máquina. La segunda sigue necesitando juicio.

Tres superficies read-only

En jesuserro.com R4 se materializa inicialmente con tres comandos.

director:audit

npm run director:audit

Resume el workspace sin modificarlo:

repository
branch
base SHA
HEAD SHA
working tree
commits ahead
changed files
CI areas
expected CI Draft
expected CI Ready
scope flags

También existe salida estructurada:

npm run --silent director:audit -- --json

La salida JSON incluye schemaVersion, de forma que otra herramienta o agente puede consumirla sin parsear prosa.

El comando no hace fetch, pull, reset, checkout ni ningún write. Describe el estado que realmente observa.

canonical:director:report

npm run canonical:director:report

El segundo comando aplica la misma idea al PostgreSQL canonical.

Su contrato es deliberadamente read-only. Puede informar de:

• conectividad;
• counts agregados;
• checkpoint/authority disponible;
• estado de materialización;
• ledger de migraciones cuando puede observarse;
• warnings sanitizados.

No muestra passwords, connection strings completas, bodies editoriales ni errores crudos que puedan contener secretos.

La intención es que el formato sobreviva a la infraestructura. Hoy la base canonical puede ser local; mañana puede estar en Neon u otro PostgreSQL. El contrato del Director no debería cambiar por ello.

PostgreSQL local ─┐
                  ├─→ canonical:director:report → humano / JSON
PostgreSQL cloud ─┘

Cuando exista una base compartida, la evolución natural es una identidad específica del Director con permisos de lectura:

CONNECT
USAGE
SELECT

pero nunca INSERT, UPDATE, DELETE ni DDL.

director:handoff

npm run director:handoff

El tercer comando compone la evidencia anterior en un paquete de entrega.

No vuelve a implementar la lógica de Git ni la de PostgreSQL: reutiliza ambas superficies.

Su objetivo es responder de forma compacta:

¿qué se ha cambiado?
¿desde qué base?
¿qué HEAD exacto debo auditar?
¿qué áreas deberían activar CI?
¿hay canonical disponible?
¿hay blockers locales observables?
¿está listo para que entre el Director?

Hay una regla especialmente importante: no inventa tests.

Si el comando no ejecutó npm test, no puede declarar PASS.

La validación local continúa siendo responsabilidad del Implementer y se adjunta como evidencia separada.

CI pasa a ser una responsabilidad operativa del Director

R4 cambia también la propiedad de CI.

El flujo normal es:

Draft PR
   ↓
Director observa CI
   ↓
¿fallo?
   ├─ no → continuar
   └─ sí
       ↓
   Director triage
       ├─ flaky / infraestructura → rerun del Director
       ├─ workflow / integración → Director o microfix dirigido
       └─ regresión de implementación → vuelve al Implementer

El Implementer sólo vuelve cuando hay algo que realmente requiere implementación.

Y vuelve con una petición focal, no con una investigación abierta del tipo «mira qué pasa con CI».

Ejemplo:

gate: canonical integration
expected: 31 reviews
actual: 32 reviews
HEAD: <sha>
error: <evidencia concreta>

Fix only this regression.

Eso convierte los tokens del Implementer en capacidad de resolución, no en capacidad de vigilancia.

Draft y Ready son dos niveles de coste distintos

La clasificación de cambios ya permitía adaptar CI al riesgo. R4 integra esa idea en el Evidence Pack.

Para una PR normal puede existir:

Draft
  → tests/check focales
  → canonical si corresponde
  → sin build completo

Ready
  → build completo
  → smokes
  → gates finales

El Implementer declara qué routing espera. El Director comprueba que la realidad coincide.

Esa comparación es útil porque detecta dos tipos de problema:

1. el código está mal clasificado;
2. el workflow no está haciendo lo que creemos.

Por tanto el routing esperado es también una especificación ejecutable del pipeline.

Documentación: el caso límite de CI mínimo

R4 no significa ejecutar siempre más CI. Significa ejecutar el CI proporcional al riesgo y bajo una responsabilidad clara.

Una modificación exclusivamente documental puede seguir una vía mucho más corta:

Markdown-only
↓
frontmatter válido
↓
diff limpio
↓
clasificación docs/content conocida
↓
PR pequeña
↓
verificación mínima necesaria
↓
merge
↓
Vercel

No tiene sentido reconstruir bases de datos, ejecutar suites no relacionadas o convertir una corrección editorial en un proceso de varios minutos si el changeset no puede afectar esos subsistemas.

La consecuencia de R4 no es «más gates» sino:

cada gate debe justificar su relación con el riesgo real del cambio.

Vercel deja de pertenecer al Implementer

En jesuserro.com, Vercel forma parte del perfil de despliegue.

El Implementer no necesita esperar Preview. El Director puede observar el check de deployment, inspeccionar el Preview cuando sea necesario y decidir si la evidencia es suficiente.

Los conectores directos —Vercel hoy, PostgreSQL/Neon mañana— son aceleradores de esta función, pero no son nuevas fuentes de verdad.

La regla es:

Implementer writes
Director reads and verifies

Siempre que sea viable, la superficie del Director debe ser read-only.

La autoridad del contenido también debe estar clara

La separación de roles operativos sería incompleta si no sabemos qué sistema manda sobre los datos.

En el frente de Reviews, R4 coincide con una decisión arquitectónica más general:

PostgreSQL
= única fuente canonical

Obsidian
= editor / interfaz de trabajo

Markdown
= working copy / materialización

Git
= versionado técnico, auditoría y deployment auxiliar

Goodreads
= evidencia externa

El Director debe auditar la fuente canonical, no inferirla a partir de una copia secundaria cuando ambas puedan diferir.

Esto explica por qué canonical:director:report importa: observabilidad y autoridad deben apuntar al mismo sistema.

Read-only no significa poco poder

Una de las lecciones de R4 es que el Director necesita mucha capacidad de observación y poca capacidad accidental de mutación.

Un buen Director puede:

• leer PR y diff;
• inspeccionar checks;
• revisar logs;
• comparar HEAD_SHA;
• consultar estado canonical;
• inspeccionar deployments;
• decidir routing;
• hacer reruns;
• proteger un merge por expected-head.

No necesita escribir en PostgreSQL para saber si PostgreSQL es correcto.

Esta asimetría es deseable:

más observabilidad
+
menos autoridad accidental
=
mejor dirección

Expected-head merge sigue siendo el cierre técnico

R4 conserva una de las invariantes importantes de revisiones anteriores: la auditoría pertenece a un SHA exacto.

Si el Director audita:

HEAD_SHA = A

el merge debe rechazar silenciosamente cualquier sustitución por:

HEAD_SHA = B

Por eso el cierre sigue usando expected-head.

La secuencia es:

HEAD A
↓
Director audit
↓
CI / deployment evidence sobre A
↓
merge permitido sólo si HEAD sigue siendo A

La decisión deja así de ser «aprobar esta PR» y pasa a ser una afirmación mucho más precisa:

apruebo exactamente esta mutación, sobre esta base y con esta evidencia.

El primer dogfooding de R4

La propia implementación de estas herramientas sirvió para probar el nuevo flujo.

El Implementer:

implementó
→ validó localmente
→ abrió Draft PR
→ entregó Evidence Pack
→ salió del loop

El Director continuó:

auditoría del diff
→ comprobación del routing previsto
→ observación de CI Draft
→ paso a Ready
→ CI completo
→ comprobación Vercel
→ expected-head squash merge
→ verificación post-merge

No hubo que devolver trabajo al Implementer.

Además, el routing pronosticado por el Evidence Pack coincidió con el ejecutado por CI. Esa coincidencia convirtió la primera ejecución de R4 en una prueba del propio modelo.

Core reutilizable frente a Project Profile

Como en revisiones anteriores, conviene separar patrón y plataforma.

Core R4

• Director e Implementer con ownership explícito;
• Implementer termina en Draft PR + Evidence Pack;
• evidencia generada por máquina cuando sea posible;
• salidas humana y JSON;
• CI observado e interpretado por el Director;
• failure routing antes de devolver trabajo;
• superficies del Director preferentemente read-only;
• validación proporcional al riesgo;
• expected-head merge;
• verificación post-merge.

Project Profile — jesuserro.com

• GitHub PR-gated;
• director:audit;
• canonical:director:report;
• director:handoff;
• GitHub Actions con routing Draft/Ready;
• PostgreSQL canonical;
• Vercel Preview y producción;
• futuro acceso PostgreSQL cloud read-only cuando exista necesidad real.

Otros perfiles

IXATU puede conservar Azure, ACR, Container Apps u otras superficies. El patrón no exige Vercel ni Neon.

Lo reusable es la separación:

build
≠ evidence
≠ observation
≠ decision
≠ deployment verification

Qué hemos eliminado del loop

R4 es también una revisión por sustracción.

Eliminamos del turno normal del Implementer:

• polling de CI;
• polling de Vercel;
• interpretación global de fallos;
• reruns;
• decisión Ready;
• merge;
• verificación post-merge.

No porque esas tareas sean poco importantes, sino porque tienen un propietario mejor.

Y eliminamos del Director parte del trabajo manual de reconstruir el estado de la PR:

• rama;
• SHA base;
• SHA cabeza;
• archivos afectados;
• routing esperado;
• estado canonical agregado.

La máquina prepara los hechos. El Director usa su tiempo en juzgarlos.

R4 en una frase

La Revisión 3 llevó el loop del código a una versión verificable. La Revisión 4 mejora quién hace cada parte del recorrido y cómo se transporta la evidencia entre ambos lados.

La nueva frontera es:

Implementer
= construir + validar localmente + entregar evidencia

Director
= observar + interpretar + decidir + integrar + verificar

El objetivo no es que el agente haga menos por hacer menos. Es que cada agente haga sólo el trabajo para el que aporta más valor.

Cuando eso ocurre, el loop se vuelve más rápido, más barato y también más verificable: menos polling duplicado, menos relato manual, más evidencia estructurada y una cadena de decisión mucho más clara.