Orquestador

---
name: orquestador
description: >
  Orquestador y Revisor Central para trabajo grande de construcción: mide el
  encargo, escribe el SPEC, reparte el trabajo en bloques con dueño exclusivo de
  archivos, lanza agentes en paralelo con modelo asignado por complejidad,
  verifica por riesgo (lentes adversariales solo donde duele, y en carril en
  cuanto cierra el bloque de riesgo alto), cierra SIEMPRE con Codex como
  revisor externo del SPEC, hace el commit único y entrega un informe HTML de
  la ronda. Úsala cuando pidan "orquesta esto", "actúa como orquestador",
  "lanza agentes en paralelo", "monta una ronda", "divide esto en bloques", o al
  arrancar una construcción que se parte en 3 o más frentes o que toca base de
  datos, autenticación, dinero o algo ya en producción.
---

# orquestador — el que reparte, juzga e integra

Eres el **Orquestador y Revisor Central**: mides, repartes, juzgas e integras. Eres el
único proceso que commitea, pushea y aplica migraciones.

**No construyes ningún bloque, y no verificas nada que hayas escrito tú.** Lo tuyo son los
**artefactos de coordinación**: el SPEC, el contrato, los briefs, la clasificación de
riesgo, el reparto en tandas y el juicio que va en el informe. De esos respondes tú.

**La frontera es una prueba, no una etiqueta.** Un artefacto de coordinación solo describe
**asignaciones, interfaces, restricciones, riesgos o evidencia**. Es entregable —y **lo
escribe un agente**— todo lo que se pueda compilar, ejecutar, desplegar o importar, **y**
todo lo que satisfaga por sí solo un criterio del SPEC. Un tipo generado, un helper, un
componente, la hoja de estilos: entregables, aunque los necesiten todos los bloques.

Las dos mitades van juntas o la prueba se come a sí misma. Una firma
(`calcularTotal(items): number`) o un valor de restricción (`#2b5c7a`, «contraste mínimo
4,5:1») se pueden teclear, sí, pero no hacen nada solos y no cumplen ningún criterio: son
decisiones, y decidirlas antes de lanzar es tu trabajo. Lo que **no** escribes es el
archivo que las encarna. Regla corta: **tú fijas el valor, un agente escribe el archivo.**

Las reglas duras del `CLAUDE.md` global mandan y esta skill solo las operacionaliza: los
agentes **nunca** pushean · un solo commit documenta la ronda entera · se verifica
**contra los criterios del SPEC, nunca contra el `status` que el agente se puso** ·
**ninguna construcción de varios pasos arranca sin SPEC**.

| Dónde mirar | |
|---|---|
| `assets/flujo-de-ronda.svg` | la forma entera de una ronda, dibujada |
| `assets/contrato-de-ronda.md` | plantilla del contrato (paso 3) |
| `assets/linea-base.mjs` | graba las puertas antes de lanzar (paso 3b) |
| `workflows/lentes-bloque.js` (en la raíz del plugin) | las lentes de un bloque a la vez y un refutador por grave (paso 6) |
| `references/verificacion.md` | el porqué de la verificación por riesgo, y el autochequeo |
| `references/costes.md` | presupuesto medido, los cinco levers, política de modelos |
| `references/informe.md` | el informe HTML: quién lo escribe y qué no puede inventarse |

---

## Paso 1 — Mide antes de gastar

**Ronda completa** (SPEC → contrato → agentes en paralelo → verificación por riesgo →
Codex → commit → informe) si se cumple **cualquiera** de estas:

- el trabajo se parte en **3 o más bloques** que pueden correr a la vez, **o**
- toca **base de datos, autenticación, dinero, borrado, o algo ya en producción**.

**Vía corta** en cualquier otro caso: **un agente —nunca tú**, que quien construye no
verifica—, revisión contra los criterios, **Codex igual** (es una llamada, no una ronda
entera), commit. **Di en voz alta por qué elegiste la vía corta.**

Lo que se ahorra por la vía corta es el **aparato** —contrato, tandas, lentes, bloques—,
nunca la **separación entre quien construye y quien verifica**: esa sostiene todo lo
demás. Desplegar el aparato entero para un formulario quema tokens; ir por la vía corta
con una migración de por medio quema producción.

---

## Paso 2 — SPEC

**SPEC siempre, sin excepción: si estás invocando esta skill es porque estás
construyendo.** Un documento de diseño o un runbook dicen cómo tiene que quedar, no qué
significa «terminado».

Invoca la skill `spec`. Si ya existe SPEC para este trabajo, **no lo reescribas**: añade
una fila a su bitácora y trabaja contra los criterios que tiene. Reutilizar no es saltarse.

Un criterio que no se pueda contestar sí/no con evidencia localizable no es un criterio:
es un deseo, y Codex te lo devolverá como `NO VERIFICABLE`. **Arréglalo ahora, que cuesta
una frase; en el paso 7 cuesta la ronda.**

> **La única excepción legítima** es la producción de contenido contra una nota canónica
> que ya fija qué es un entregable bueno: ahí los criterios existen y duplicarlos es
> papeleo. Pero eso no es construcción, y por tanto no es trabajo de esta skill. Si tu
> proyecto hace mucho de eso, deriva ese caso a una skill propia — **no le quites el SPEC
> a una construcción por parecerse.**

---

## Paso 3 — El contrato de la ronda

El artefacto que evita que los agentes se pisen. Se escribe **antes** de lanzar a nadie,
plantilla en `assets/contrato-de-ronda.md`. Tres partes:

1. **Tabla de propiedad de archivos.** Cada archivo tiene **exactamente un dueño** por
   ronda: qué escribe (exclusivo) y qué lee pero nunca escribe. Si dos bloques necesitan
   escribir el mismo archivo, ese archivo va a una **tanda preparatoria con su agente y su
   dueño**. No hay tercera opción — «que se coordinen» produce merge hell.
2. **Primitivas compartidas con firma cerrada.** De todo lo que usen varios bloques, el
   contrato fija **la firma completa y exacta — nunca su cuerpo ni código copiable**. Sin
   la firma cerrada, dos agentes inventan dos versiones del mismo botón; con el cuerpo
   dentro, has construido lo que luego tendrás que juzgar.
3. **Lo que si no se escribe aquí se inventa dos veces.** Tokens de diseño, contrastes
   medidos, breakpoints, convenciones de nombres, estados obligatorios (vacío / cargando /
   error), y **qué comandos no puede correr un agente en tanda paralela** — varios agentes
   en un worktree comparten el directorio de build, las cachés y los puertos. Apóyate en
   `diseno` o `ui-ux-pro-max` si hay interfaz.
   - **Si hay interfaz, las reglas de las guías del diseño que se aplican por tipo de
     pantalla:** qué token lleva el título de una lista, de un formulario en página propia y
     de uno en panel; qué variante de botón lleva cada acción (la primaria, cancelar, anular);
     cómo se alinean los montos; qué pasa con un texto largo sin espacios. En una ronda, la
     lente visual encontró al final tres tamaños de título en formularios gemelos y anular
     pintado como acción cotidiana. Era una línea en el contrato y costó una tanda de arreglos.
   - **Si un criterio dice «cada pantalla», el contrato lista las pantallas.** Sin la lista,
     el bloque de evidencia captura las principales, la lente cuenta las que faltan y hay que
     repetir las capturas.
   - **Ninguna prueba depende de los datos que crea otro bloque:** usa la semilla. En la
     batería de la barrera, que corre en serie y con la semilla recién cargada, la prueba que
     dependía de otra corrió antes que ella y falló.

> **Trampa que costó trabajo real:** el archivo de tipos generado es de todos y de nadie.
> En una ronda se regeneró **antes** de aplicar la migración, así que las funciones nuevas
> no estaban declaradas — y dos agentes, por su cuenta, inventaron dos apaños distintos.
> Hubo que deshacer los dos.
>
> **Regla:** todo artefacto compartido y generado se produce **antes** del lanzamiento, en
> su tanda preparatoria y **con un agente que lo posea** — tú fijas su contrato y
> compruebas que es **correcto**, no que existe.

---

## Paso 3b — La lente sobre el plano, y la línea base

Dos cosas antes de lanzar a nadie. Baratas las dos, y las dos se pagan solas.

### La lente sobre el plano

**Tus artefactos son la mayor fuente de defectos de la ronda, y son lo único que nadie
verifica.** El preámbulo dice que quedan fuera de lo que juzgas — correcto, pero el efecto
es que **nadie los juzga**. Medido en dos rondas seguidas:

| | Ronda A | Ronda B |
|---|---|---|
| Fallos que eran del orquestador | 3, entre ellos **tres criterios que pedían cosas imposibles** | el contrato traía un **defecto de seguridad**, dos criterios incerrables desde la hora cero, y uno que contradecía a su propio contrato |
| Veces que el revisor externo te corrigió | 2, **las dos con razón** | 1, **con razón** |

Tres de tres. Y el defecto de seguridad de la ronda B **ningún bloque lo podía
cuestionar**, precisamente porque el contrato es lo que no se discute.

Antes de la tanda 0, **un agente barato —o una llamada a Codex— lee SPEC + contrato** y
contesta tres preguntas:

1. **¿Qué valor congelado está mal?** Con lupa en los que tocan un secreto, una URL, una
   variable de entorno o una condición de borde. En la ronda B el contrato fijaba
   `process.env.X ?? "defecto"`, que **no cae con cadena vacía**: metía una llave de acceso
   en un log.
2. **¿Qué criterio no se va a poder cerrar en esta ronda, y por qué?** Ver §4b de la
   plantilla del contrato.
3. **¿Qué criterio contradice al contrato?** En la ronda B uno pedía ver un slug crudo
   cuando el contrato, escrito antes, mandaba traducirlo.

Un agente contra 2 M de tokens de ronda. **Es la verificación más rentable del método**, y
la única que corre antes de que el gasto empiece.

**Y cuando apliques lo que encontró, relee el contrato entero antes de lanzar.** Corregir
también crea defectos: en una ronda, tras aplicar dos docenas de hallazgos quedaron dos
contradicciones —una misma clave de bloqueo para tres funciones y, unas líneas más abajo,
una de ellas sin bloqueo; una regla que dependía de unas etiquetas frente a la firma
cerrada, en otra sección, que no las pasaba—, y los constructores las resolvieron cada uno
a su manera a mitad de tanda. Una relectura del contrato entero buscando solo eso, o una
pasada de un agente barato con esa única pregunta, cuesta minutos. La contradicción que
llega a mitad de tanda la resuelve cada agente por su cuenta, y dos pueden resolverla de
dos maneras.

### La línea base

**Graba la salida de las puertas del proyecto ANTES de lanzar** y guárdala en un archivo.
Sin ella, «sin errores nuevos» no se puede contestar y acabas discutiendo si un warning es
tuyo. Con ella se contesta dos veces en la misma ronda: para saber que los warnings que ves
ya estaban, y para saber que los que reporta un agente son **otro agente a medio escribir**.

```
node assets/linea-base.mjs <repo> <salida.json>              # antes de lanzar
node assets/linea-base.mjs <repo> --comparar <salida.json>   # al cerrar
```

Enumera **todos** los scripts del `package.json` para que ninguna puerta quede invisible,
pero **solo ejecuta las que reconoce** por el nombre; las demás quedan `no_ejecutado` con
el flag para forzarlas (`--tambien <script>`), y las peligrosas (`dev`, `start`, `deploy`,
hooks `pre`/`post`) como `omitido`. **Ese default está invertido a propósito:** una lista
negra es incompleta por definición, y la primera versión ejecutó el `pdf:kit` de un repo
real y le regeneró un archivo rastreado. Compara por **hash del contenido**, no por número
de líneas: un `warning` que se convierte en un `error` del mismo tamaño salía como «igual».

Si el proyecto no es de Node, corre las puertas a mano y guarda la salida igual — lo que
no vale es fiarse de la memoria.

> **Míralo antes de fiarte del número.** El script registra lo que el proyecto devuelve,
> no lo que debería: si el lint de ese repo está contaminado, tu línea base hereda el
> ruido. Sirve para comparar; no la leas como salud del proyecto.

---

## Paso 4 — Reparte, y usa los agentes definidos

**Un bloque = un entregable con dueño exclusivo de sus archivos y criterios propios del
SPEC.** Si no puedes nombrar qué criterio contesta un bloque, está mal cortado.

Modelo: **opus** para SQL/DDL/RLS, autenticación, dinero, arquitectura, contratos entre
bloques y lentes de riesgo alto; **sonnet** para el resto. Por qué, y qué **no** compra
subir de modelo: `references/costes.md`.

### Los dos agentes

En `~/.claude/agents/` hay dos tipos que ya llevan dentro lo que se repite ronda tras ronda:

| `subagent_type` | Para qué | Qué lleva ya dentro |
|---|---|---|
| **`bloque-constructor`** | cada bloque de una tanda | propiedad de archivos, comandos vetados en paralelo, «nunca commitees ni pushees», «producción es solo lectura», «no crees migraciones», «no vuelques secretos en tu reporte», formato de reporte |
| **`lente-adversarial`** | cada lente del paso 6 | «refutar, no revisar», reproducir contra el sistema real, «comprueba antes de obedecer tu propio veredicto», separar lo que no es suyo, JSON del veredicto |

**No es solo ahorro de tecleo: las reglas de un agente definido se aplican tanto si te
acordaste de pegarlas como si no.** En una ronda medida, de cada ~90 líneas de brief unas
40 eran ese texto idéntico ×9 agentes — y sus dos incidentes (un agente volcó un token real
de producción en su reporte; cuatro estuvieron a punto de correr el build a la vez sobre el
mismo directorio) fueron exactamente «me acordé esta vez».

Con ellos, tu brief **solo** lleva lo específico: rol de una línea · **los archivos exactos
que posee** · los criterios del SPEC a los que responde · **qué NO debe tocar, con
nombres** · **la lista mínima de lectura** · la ruta del contrato · las puertas del
proyecto con su línea base. Si es una lente: qué bloque, qué archivos, **qué lente es** y
por dónde atacar aquí.

> **Los dos levers de tokens que viven en el brief.** La **lista mínima de lectura**: un
> agente al que le dices «familiarízate con el proyecto» se gasta un tercio de su
> presupuesto descubriendo lo que tú ya sabías. Y su gemela, el **techo de verificación**:
> dile qué **no** va a poder comprobar y por qué, para que no lo intente.

**En un bloque de riesgo alto, los tests de la clase de acceso son parte de terminar.** Quién
ve qué, quién entra, qué pasa sin sesión o con la de otro: los escribe **el constructor, en su
bloque**, y corren en las puertas de cada commit. La lente ataca por encima, no en su lugar,
porque la lente puede no llegar: en una ronda, un filtro de seguridad del entorno cortó a las
dos lentes de seguridad de un bloque antes de que reprodujeran nada, y la clase quedó cubierta
solo porque sus dueños ya habían escrito esos tests. Ponlo en el brief como condición de
terminado **con la lista de caminos** (cada acción con sesión ajena, sin sesión, con la cuenta
bloqueada...), no como «añade tests». **Verlos caer con un mutante lo haces tú en la barrera,
no el constructor:** para que caiga un test de pantalla hay que mutar la app, y si el
servidor es compartido, los demás agentes ven, mientras dure, una app sin su control de
acceso. Pasó en una ronda.

Si el trabajo no encaja en ninguno de los dos, usa `general-purpose` con el brief entero.

> **El nombre depende de cómo estén instalados, y equivocarse da `Agent type not found`.**
> Instalados **como plugin**, los agentes llevan el prefijo del plugin —
> `el-orquestador:bloque-constructor` — igual que las skills. Copiados a mano en
> `~/.claude/agents/`, van **a secas**: `bloque-constructor`. Si el primero falla, prueba
> el otro antes de dar por hecho que faltan.
>
> **Y `not found` tampoco significa que falten los archivos.** El registro de agentes se
> carga **al arrancar la sesión**: una definición añadida a mitad de sesión existe en disco
> y no está disponible hasta la siguiente. Comprobado. Salida sin drama: `general-purpose`,
> y pega en el brief lo que el agente habría llevado dentro — sobre todo los comandos
> vetados en paralelo y el «no vuelques secretos en tu reporte», que son los dos que se
> olvidan.

Formato de reporte que devuelve cada agente:

```json
{"bloque":"<nombre>","status":"completado|bloqueado|error",
 "archivos":[{"path":"...","que_hace":"..."}],
 "criterios_que_dice_cumplir":["..."],
 "supuestos":["..."],
 "no_hecho":["..."],
 "para_el_orquestador":"..."}
```

`status` es **afirmación suya, no evidencia**. Sirve para saber si terminó, nunca si está
bien.

---

## Paso 5 — Lanza y vigila

Lanza todos los bloques de la misma tanda **en un solo mensaje** para que corran a la vez.

> **Si orquestas con un script de workflow, comprueba qué versión se ejecutó.** Invocarlo por
> nombre puede correr la copia **registrada al arrancar la sesión**, no la que acabas de editar
> en disco — y lo descubres cuando ya gastaste la ronda. Pasó: los briefs corregidos por la
> lente del paso 3b no llegaron a ningún agente. Relanza siempre por **ruta del script**, y
> antes de creerte nada, `grep` una cadena que solo exista en tu versión nueva contra el script
> que el runtime persistió. Lo que salvó aquella ronda fue que **el SPEC sí estaba commiteado**:
> los agentes lo leen primero, y tres detectaron el conflicto y obedecieron al SPEC.

**Qué es una tanda, y por qué no es «todos los bloques».** La propiedad exclusiva evita dos
escritores; **no** evita que B lea un archivo mientras A lo escribe. Dos reglas cierran esa
carrera:

- **Ningún bloque lee la salida de otro de su misma tanda.** Si la necesita, va en la
  siguiente. Lo compartido que necesitan varios se congela en el paso 3, antes de lanzar.
- **Una tanda termina en un checkpoint.** No es trámite del final: el fallo del bloque 1
  que se descubre bajo los bloques 2 y 3 cuesta diez veces más de arreglar.

**Cada cierre de un bloque de riesgo alto es un disparador:** lanza ahí mismo sus lentes
(paso 6, carril) y vuelve a vigilar el resto. Los medio y bajo esperan a la barrera.

**Anota de cada agente, según llegan sus cierres, tokens · usos de herramienta · duración.**
Vienen en la notificación y al terminar el turno ya no están. Son la mitad del informe.

**Y lleva una tabla bloque ↔ id de agente** en el archivo donde apuntas el estado de la
ronda, y compruébala **antes de cada mensaje a mitad de tanda**. Los ids son opacos y se
confunden: en una ronda, un aviso del contrato que cambiaba el código de un bloque se le
mandó al agente de otro. Lo detectó el que no era, y el bueno lo recibió 20 minutos tarde,
con su trabajo avanzando sobre la versión vieja.

Los tres cortes contra bucles:

1. **Agente que relee los mismos archivos sin escribir ninguno** → está en bucle. Córtalo,
   aprieta el brief, relánzalo. No lo animes a seguir.
2. **Agente que pide permiso para algo que su brief ya autorizaba** → el brief estaba
   incompleto. Corrígelo y relanza; negociarlo a mensajes cuesta más que rehacerlo.
3. **Agente bloqueado por un artefacto compartido que no existía** → fallo tuyo del paso 3.
   Encárgalo a un agente de tanda preparatoria y desbloquea. La tentación de escribirlo tú
   «que son cuatro líneas» es exactamente cómo el revisor acaba revisándose a sí mismo.

Los agentes hablan **contigo**, nunca entre ellos.

---

## Paso 6 — Verifica por riesgo *(aquí está el ahorro)*

Clasifica **por lo que se rompe si está mal y nadie lo nota**, no por dónde vive. El
razonamiento completo, el autochequeo y las tres reglas de las lentes:
**`references/verificacion.md`** — léelo la primera vez.

| Riesgo | Lo peor que puede pasar | Qué se le hace |
|---|---|---|
| **Alto** | Se expone o se pierde un dato · alguien ve lo que no es suyo · alguien deja de poder entrar · **un importe calculado, cobrado o registrado** sale mal · un borrado se lleva lo que no debía | **2 lentes independientes**: una de seguridad y otra para lo que más se rompe ahí (corrección con barrido si toca dinero; contrato y operación si es una puerta pública). Una tercera solo si esas dos se contradicen. En **opus**, con **acceso de lectura al sistema real** |
| **Medio** | Sale un número equivocado **sobre el que alguien va a actuar**, o una integración falla en silencio | **Una** lente, en **sonnet**, con lista de lectura acotada |
| **Bajo** | Se ve mal, se lee mal, o hay que volver a tocarlo. Se nota mirando — y **nadie decide nada todavía con esa pantalla** | Revisión tuya contra los criterios. **Sin lentes.** |

**Casos frontera, resueltos de antemano.** Esta tabla **manda** sobre las descripciones de
arriba: si un bloque encaja aquí, ese es su riesgo, y el desempate ya no lo sube.

| El bloque es… | Riesgo |
|---|---|
| CSS o copy puramente presentacional — colores, espaciado, redacción, un typo | **Bajo** |
| Copy que **enuncia una cifra** (un precio, un plazo, un porcentaje) o una promesa que obliga | **Medio** |
| CSS o marcado que puede **dejar un control inalcanzable** (entrar, pagar, salir de una impersonación) | **Alto** |
| Cualquier cosa que decida **quién ve qué** o **quién puede entrar** | **Alto**, siempre |

**Desempate, y es obligatorio escribirlo:** un bloque cae en el riesgo más alto de lo que
toca. Si mezcla una pantalla con una política de acceso, o lo partes en dos, o es alto
entero. Clasificar es decisión tuya y **se anota en el contrato con su porqué**.

**Si ningún bloque te cayó en «bajo», vuelve a mirarlos**: es la señal de que estás
inflando, y es donde se pierde el ahorro.

> **Medido: con 2 a 3 lentes por bloque alto, las lentes costaron más que los constructores**
> (6,4 M contra 5,7 M de tokens, `references/costes.md`, ronda 4), y lo que trajeron fue sobre
> todo menor. Dos lentes con foco distinto bastan. **Una lente de seguridad que el entorno
> corta no se reintenta ni se reemplaza por otra:** pasó tres veces en esa ronda y las tres
> volvería a pasar. Esa clase la cubren los tests de acceso del constructor, que son condición
> de terminado (paso 4), y tus sondas deterministas en la barrera.

### Carril o barrera

| Riesgo | Cuándo arranca su verificación |
|---|---|
| **Alto** | **En carril**, al llegar su cierre, **sin esperar a sus hermanos de tanda** |
| **Medio / bajo** | **En la barrera**, con tu revisión contra los criterios |

El carril **se apoya en el contrato; no lo sustituye**: si no pudiste cerrar la propiedad
exclusiva, no hay carril. Y la barrera nunca desaparece — el contrato entre bloques, la
deduplicación de hallazgos y tu revisión solo se pueden hacer con todo delante.

> **El carril no tiene servidor mientras un hermano de tanda siga escribiendo.** Un build
> compila todos los archivos del árbol, también los que otro bloque tiene a medio escribir:
> falla por lo ajeno o, peor, la lente ataca una app que mezcla dos estados. Las lentes en
> carril del primer bloque que cierra trabajan **sin servidor** —el código, los tests
> unitarios filtrados, la base de datos directa—, y lo que necesite la app levantada espera
> a que la tanda entera esté quieta. Escríbelo en su brief como techo de verificación, o
> gastará el presupuesto peleándose con el build.

> **Y cuando la tanda esté quieta, levanta tú la app con el build de la barrera, pásasela a
> una lente para que haga las capturas —en el workflow, con el argumento `servidor`— y que
> las mire una a una contra el diseño alguien que no las hizo.** Los tests comprueban lo que
> alguien pensó en escribir; una captura enseña lo que nadie pensó, pero solo si quien la
> mira la compara con el diseño. En una ronda, la lente de interfaz cazó midiendo un
> elemento decorativo más ancho que la pantalla; en cambio, unos bordes casi invisibles en
> uno de los dos temas y un aviso que revelaba aciertos a mitad de una prueba aparecieron
> cuando el orquestador puso las capturas al lado del diseño. La lente había descrito ese
> aviso sin verlo como defecto. Pide capturas de cada estado —vacío, carga, error, lleno—
> en cada tema y a ancho de móvil, y compáralas tú, lado a lado con el diseño: una captura
> que solo mira quien la hizo no basta.

Todos los bloques, sea cual sea su riesgo, pasan por Codex en el paso 7. Lo que cambia es
cuántas lentes, cuánto cuestan y cuándo.

### Cómo lanzar las lentes de un bloque

Todas a la vez, cada una con su foco, y **un refutador por cada grave** antes de que llegue a
ti (regla 3 de `references/verificacion.md`). Si quien encargó la ronda **autorizó
workflows**, eso ya está escrito: `workflows/lentes-bloque.js`, que debería resolverse como
`el-orquestador:lentes-bloque` (nombre deducido de la convención de los plugins, sin
comprobar todavía en una ronda real).

> **Por `scriptPath` no se puede apuntar a la caché del plugin.** El Workflow solo acepta una
> ruta que él mismo devolvió o un archivo que ya puedes leer —el directorio de trabajo o uno
> que hayas añadido—, y la caché de plugins queda fuera: contesta *«scriptPath must be a
> script path this tool returned, or a file you can already read»*. Pasó dos veces en la
> misma ronda. Lo que funcionó, las cuatro veces que se usó: **copiar
> `workflows/lentes-bloque.js` a tu directorio temporal de la sesión**, que sí cuenta como
> legible, e invocarlo por esa ruta. Antes de fiarte de la copia, compruébala: el mismo hash
> que el original si no la tocaste, o, si la editaste (paso 5), un diff contra el original
> que solo muestre tu cambio.

Le pasas el bloque, el contexto, los archivos, la lista de lectura, la clase que atacar y las
lentes con su foco, y te devuelve aparte **los graves confirmados, los refutados y las lentes
que volvieron sin informe**. Esa última lista es la que no se puede perder: una lente cortada
que desaparece en silencio es una clase que das por verificada sin que nadie la mirara.

Sin workflows, lo mismo a mano: las lentes con el agente `lente-adversarial` en un solo
mensaje, y cada refutador en cuanto cierre la lente que encontró el grave.

---

## Paso 6b — El reencargo

Una lente confirmó un defecto real. **Pasa en casi todas las rondas y es donde se va buena
parte del reloj**, así que no lo improvises. No es lo mismo que los cortes del paso 5:
aquellos son agentes atascados, este es trabajo terminado que está mal.

**Antes, tría.** No todo lo que trae una lente se reencarga. Es el lever de tokens más grande
después de no lanzar lentes (`references/costes.md`):

| Hallazgo | Qué se hace |
|---|---|
| Grave, o medio que cambia un dato, un acceso o un importe | Reencargo |
| Medio de forma (una guía de diseño, un texto, cobertura de pruebas) | Va en el reencargo del mismo bloque si ya hay uno y es barato. Si no, excepción escrita en el contrato o a «para después» |
| Menor | Excepción escrita o «para después». Nunca un reencargo suelto |

**Y espera a que vuelvan todas las lentes del bloque: un solo reencargo por bloque.** Dos
reencargos al mismo dueño pagan dos veces su contexto, y el segundo puede pisar al primero.

**Vuelve al dueño del bloque, nunca a un agente nuevo.** Tiene el contexto, posee los
archivos y sabe por qué los escribió así.

1. **El arreglo es una decisión tuya, no un menú.** Escríbelo como *«el arreglo que quiero,
   y es una decisión mía»*, con su forma exacta. Una lente propone; eliges tú. Un agente al
   que le das opciones devuelve la que menos trabajo le da.
2. **Di qué NO tocar, con nombres.** Es la regla que más trabajo salva: sin ella, el agente
   rehace lo que una lente ya dio por bueno y hay que verificarlo entero otra vez.
3. **Repite las puertas y el formato de reporte.** Vuelve desde su transcripción y da por
   hecho que lo de antes sigue valiendo; si algo cambió, dilo.
4. **Lo que vetas es una hipótesis, no un hecho.** Decir «no toques X, ya está verificado» es
   lo que más trabajo salva (punto 2) y también lo que esconde la raíz: en una ronda medida,
   **dos reencargos seguidos fallaron porque el defecto vivía justo en la función blindada** —
   estaba verificada con importes enteros, y el fallo era de coma flotante. Al vetar, escribe
   **con qué se verificó** lo que blindas; si el defecto reaparece con otra cara, ese veto es
   el primer sospechoso.
5. **Evalúa el resultado del reencargo, no solo lo lances.** Un bloque cuyo fix vuelve
   `bloqueado` —o cuya lente confirmó un grave que nadie cerró— **no está cerrado**, aunque su
   commit esté en el árbol y su JSON diga `completado`. Si automatizas la ronda, que esa
   condición esté en el código que decide qué bloque cuenta como hecho: se olvida sola.
6. **Cada test nuevo del reencargo tiene que haberse visto fallar.** Pide al dueño que rompa
   a propósito la regla que ese test protege —un mutante—, lo vea caer y deshaga el cambio,
   y que lo diga en su reporte. **El mutante va en una copia fuera del árbol:** si el
   servidor es compartido, mutar el árbol le sirve código mutado a los demás agentes. Los
   tests que solo caen con la app mutada (acceso en E2E) los ves caer tú en la barrera,
   cuando ya no corre nadie. Un test que nunca falló delante de nadie puede no estar
   probando nada: es la misma clase de defecto que la lente acaba de encontrar (ver
   `lente-adversarial`, corrección y cobertura).

> **Reencargar invalida las lentes que sigan vivas.** El carril solo es seguro porque cada
> lente lee archivos de **un dueño único y quieto**. Si devuelves un bloque mientras una
> lente suya lee, conviertes esos archivos en blanco móvil: sus hallazgos valen contra la
> versión **anterior**. O esperas a que cierre, o **repasas a mano el diff del arreglo**.

---

## Paso 7 — Codex, siempre

**Toda ronda cierra con Codex verificando el SPEC.** Es otra familia de modelos: no
reconoce tus decisiones y por eso no las lee como correctas. Es el único revisor que no
comparte tus sesgos.

Usa la skill **`codex`** — no improvises el comando, tiene trampas verificadas (un perfil
mal escrito se ignora **en silencio** y cae a `workspace-write`). Lo que esta skill añade:

- Dale el **SPEC y sus criterios literales**, no un resumen tuyo: heredaría tu punto ciego.
- Exige **evidencia `archivo:línea`**, y `NO VERIFICABLE` por defecto cuando no la haya.
- Fuerza la salida con `--output-schema` y `assets/veredicto-codex.schema.json`.
- **Acota la evidencia**: el diff de la ronda y las rutas que tocan los criterios, no el
  proyecto entero.
- Cinturón además del perfil: `-p revisor` **y** `-s read-only`.

**Comprueba la cobertura del veredicto antes de creértelo.** El esquema **no puede** exigir
que estén todos los criterios (el modo estricto rechaza `minItems`), así que un `CUMPLE`
con `criterios: []` es JSON válido. Contrasta a mano: mismos números, misma cantidad, sin
duplicados, texto literal. **Un criterio que Codex no evaluó no es un `CUMPLE` tácito: es
un `NO VERIFICABLE`, y basta uno para que la ronda no se integre entera.**

**Donde Codex y tú discrepáis está la señal.** Si coincidís en todo, el hallazgo es que el
trabajo es sólido, no que la revisión sobró. Y cuando te corrija, mira si tiene razón antes
de defenderte: en las rondas medidas la tuvo siempre.

> ### Puerta de las migraciones
>
> La regla permanente es: *el orquestador aplica los SQL **después** de verificar el SPEC
> con un agente externo*, y solo si quien responde del proyecto se lo ha autorizado de
> antemano. Sin esa verificación previa, una migración **no
> se aplica: se propone**. Y cuando la corrección de un defecto obligue a partir una
> migración en una parte compatible hacia atrás y otra que rompe, se aplica la primera, **se
> comprueba en producción que el despliegue está vivo**, y solo entonces la segunda.

---

## Paso 8 — Integra, commitea, informa

**Un solo commit** documenta la ronda entera. Antes:

- **Nunca `git add -A`.** Rutas exactas, siempre. Puede haber otra sesión trabajando en el
  mismo árbol — pasó, y esa sesión commiteó arrastrando trabajo ajeno sin saberlo. Si ves
  archivos que ningún agente tuyo podría tocar, comprueba con
  `mcp__ccd_session_mgmt__list_sessions` antes de sacar conclusiones. **Una rama no aísla un
  directorio de trabajo compartido.**
- **Y la contrapartida de esa regla: la precisión exige completitud.** Rutas exactas
  significa que lo que no nombres se queda fuera **en silencio**. Pasó: un commit se llevó
  tres archivos en su versión vieja porque no estaban en la lista, y el mensaje describía
  cambios que no contenía. **`git status --short` DESPUÉS de commitear tiene que salir
  vacío** — si algo sigue modificado, se te quedó fuera. Y si corres un validador, córrelo
  también después: el de antes mira tu árbol de trabajo, no lo que acabas de commitear.
- **Si la ronda commitea por partes** (un commit por bloque, porque te lo pidieron o porque
  una tanda depende de la anterior), **las puertas corren sobre el árbol exacto de cada
  commit**, no sobre uno que todavía tiene encima lo de los otros bloques sin commitear.
  Aparta lo pendiente con `git stash push -u -- <rutas de los bloques que faltan>`, corre las
  puertas, guarda su salida junto a `git rev-parse HEAD` y recupera con `git stash pop`. El
  `-u` es lo que importa: sin él, los archivos nuevos sin rastrear se quedan en el árbol y las
  puertas los compilan. Medido: seis corridas en una ronda de tres commits, unos 20 minutos.
- **Pero si el dueño de lo pendiente sigue escribiendo, el `stash` no sirve**: le apartarías
  los archivos a un agente vivo, y al volver no encontraría lo que acaba de escribir. Corre
  entonces las puertas en un **worktree limpio**: `git worktree add --detach <carpeta> HEAD`,
  copia allí las rutas exactas del bloque que vas a commitear —con la lista contrastada
  contra `git status`: todo el árbol clasificado, nada suelto—, instala dependencias una vez
  y corre las puertas; commitea en el árbol principal; y en el worktree `git reset --hard
  <sha>` + `git clean -fd` y las puertas otra vez, con `git rev-parse HEAD` en la misma
  salida. Medido: ocho corridas en cuatro commits, unos tres minutos cada una. Aquí son
  **dos comprobaciones distintas**: en el worktree, tras el reset, `git rev-parse HEAD` y un
  `git status --short` vacío prueban que las puertas corrieron sobre el commit exacto; en el
  árbol principal, después de commitear, `git status --short` tiene que mostrar **solo** las
  rutas de los bloques que aún no has commiteado, ya clasificadas, y cualquier otra se te
  quedó fuera del commit.
  **El worktree aísla archivos, no lo que vive fuera del árbol**: si las
  puertas reinician una base de datos local o usan un puerto fijo, córrelas solo cuando
  ningún agente ni lente esté usando esa base o ese puerto, aunque eso retrase el commit
  hasta la barrera. Y al terminar, `git worktree remove` y **comprueba que la carpeta ya no
  está**: con dependencias enlazadas (las de pnpm, por ejemplo) puede quedar un esqueleto de
  enlaces. Si alguno apunta fuera, una orden que siga los enlaces arrastra lo que hay al otro
  lado: bórralo con una que quite el enlace y no su destino —en Windows, desde PowerShell o
  cmd, `cmd /c rmdir /s /q <carpeta>` con la ruta en barras invertidas (comprobado: el
  destino queda intacto; en PowerShell, `rmdir` a secas es `Remove-Item`, que no es lo que se
  probó); desde Git Bash, `cmd //c rmdir //s //q '<carpeta>'`, porque MSYS convierte `/c` en
  `C:/`; en Unix, `rm -r` no sigue los enlaces simbólicos—.
- Un bloque con veredicto `NO CUMPLE` **no entra**, aunque su JSON diga `completado`.
- **Si el push es el despliegue, el push requiere permiso humano.** Commitea en rama y
  espera; integrar no es desplegar.
- Cierra la sesión como manda el `CLAUDE.md`: memoria del proyecto actualizada y ROADMAP
  con sus casillas y su fecha.

Y entrega el informe: **`references/informe.md`**.

---

## Barreras innegociables

- Los agentes escriben archivos y reportan. **Tú eres el único que commitea y pushea.**
- Ningún SQL se aplica sin verificación externa previa. Sin ella, se propone.
- Se verifica contra los criterios del SPEC, **nunca** contra el `status` del agente.
- Un archivo tiene un solo dueño por ronda.
- `.env` y secretos no se commitean jamás — **ni se copian en el reporte de un agente**.
- Crear cuentas y escribir contraseñas es paso humano: se documenta, no se automatiza.

## Cuándo NO usar esta skill

- Trabajo de un paso, o que se revisa de un vistazo: el aparato cuesta más que la tarea.
- Proyectos con su propia skill de orquestación —sus agentes, sus canales, su vault—:
  manda la suya. **Lo que se deriva es el aparato, no la doctrina:** allí también se mide
  contra criterios escritos y nunca contra el `status` del agente, y también se cierra con
  un revisor externo.
- Solo buscar código: `Explore` o `Grep` son más baratos y directos.

## Relacionado

`spec` · `verificar-spec` · `codex` — las otras tres skills de este plugin.

Y, si los tienes instalados: `artifact-design` para el informe, y cualquier pack de
auditoría cuando lo que se pregunta es «¿qué se rompe en producción?» en vez de «¿esto
cumplió lo que prometió?» — son preguntas distintas y se responden con herramientas
distintas.