# Pipeline AI4M · piezas comunes (wave 0, 2026-09-09)

Inspirado en el diseño de OpenMontage (no en su código): playbook único, plan de edición con esquema, compuerta antes del render, reporte final con esquema, registro de decisiones.

| Archivo | Qué es | Cómo se usa |
|---|---|---|
| `ai4m-playbook.yaml` | Fuente única de estilo y reglas: colores, tipografías, receta DOAC, placas, gráficos, ventanas, miniaturas, edición, verificación | Todo script nuevo lo lee con `yaml.safe_load`. Cambiar un valor aquí, no en los scripts |
| `esquema-episodio.json` | JSON Schema del plan único de un episodio: planos, excluidos, captions, placas, gráficos, ventanas, audio | Lo aplica `validar_plan.py` |
| `validar_plan.py` | Compuerta previa al render. Sale 0 (PASA) o 1 (BLOQUEA) | `python3 validar_plan.py episodio-epN.json [--json]` |
| `final_review.py` | Reporte final tras el render, escribe `final_review-<version>.json` | `python3 final_review.py episodio-epN.json --video salida.mp4 [--cap DIR] [--img DIR] [--url URL]` |
| `convertir_actuales.py` | Genera `episodio-ep1.json` y `episodio-ep2.json` desde los planes reales de los episodios 1 y 2 | Solo para los episodios ya editados; el episodio 3 se escribe directo en el formato único |
| `decisiones-epN.jsonl` | Registro de decisiones con fecha, motivo y quién aprobó | Una línea por decisión, se agrega al tomarla, no al final |

## Qué valida `validar_plan.py`

- Esquema del plan y coherencia de planos (contiguos, cubren el episodio, cuadros = duración por fps).
- Captions: dentro de un solo plano, duración mínima, línea clave con mínimo de letras, corrimiento par, corrimiento 0 en planos con rótulo, mismo lado y corrimiento por plano, sin solapes, sin caer sobre intervalos excluidos (solape mayor a 1 s falla, tocar el borde avisa).
- Pantalla completa (gráficos y ventanas): tope de duración, entrada y salida en corte salvo motivo declarado, etapas dentro del intervalo y con duración perceptible, sin solapes entre sí, aviso si tapan un caption o van muy pegados.
- Huecos: aviso si hay más de 8 s seguidos sin ningún overlay fuera de los intervalos excluidos.

Mordida del 9-sep: con cuatro violaciones inyectadas en el plan del ep2 (caption que cruza corte, línea clave de 3 letras, corrimiento impar, ventana solapada de 34 s) el validador bloqueó y nombró las cuatro.

## Orden de trabajo para un episodio nuevo

1. Detectar planos y escribir `episodio-epN.json` (base, planos, excluidos con motivo, overlays).
2. `validar_plan.py` hasta PASA.
3. Renderizar por tramos con cuadros exactos (los `armar.py` de ep1g y ep2caps son la referencia hasta que exista el armador único).
4. `final_review.py` con `--url` tras publicar con nombre nuevo.
5. Anotar cada decisión en `decisiones-epN.jsonl` en el momento de tomarla.

## Pendiente (waves siguientes)

- Armador único que lea `episodio.json` (hoy hay uno por episodio).
- Reglas CHAI en el informe de `content-audit-gate`.
- `costos-epN.jsonl` con estimado y real por generación.
- Tablero vivo en playgrounds generado desde estos archivos.