/ C01 · 4
← Clasificación de imágenes C01 · Estación 4 de 12

Gate de evaluación y registry

¿Quién decide, y con qué números, que el modelo nuevo puede reemplazar al de producción?

Estás aquí4 · Gate de evaluación y registry

Arranca en 3 pasos

lo vital

Necesitas: Docker Desktop corriendo, con ≈ 700 MB libres para las imágenes de RustFS y MLflow · Python 3.11 o más nuevo (se probó con 3.14.3) y ≈ 1.1 GB para el entorno virtual (PyTorch) · git (con tu nombre y correo configurados) · Internet la primera vez (los paquetes, las imágenes y Fashion-MNIST) · Los puertos 9500, 9501 y 5500 libres en tu Mac

2

Levanta el mundo

Terminalarranque
unzip c01-gate.zip && cd c01-gate
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
docker compose up -d --wait
python mundo/crear.py
git init && git add -A && git commit -m "kit recién descomprimido"
3

Verifica

Terminal
python verificar.py mundo
Listo cuando: verificar.py mundo en verde: los buckets, los snapshots, el examen, classifier v1–v3 con @champion, los dos candidatos y git. Ya puedes practicar.
¿Algo falló al levantar?
Ojo: El 5000 lo ocupa AirPlay en macOS: por eso MLflow está en el 5500 (y el S3 en 9500, para no chocar con las estaciones anteriores).

python3 -m venv .venv && source .venv/bin/activate · Tarda unos minutos la primera vez (PyTorch pesa ≈ 1 GB). Desde aquí, cada terminal nueva necesita source .venv/bin/activate.

SalidaSalida real · python3 -m venv .venv && source .venv/bin/activate
Python 3.14.3
1.1G

docker compose up -d --wait · La interfaz de MLflow queda en http://localhost:5500: ahí están las corridas del equipo y el modelo classifier.

SalidaSalida real · docker compose up -d --wait
 Container taller-c01-gate-s3-1 Healthy 
 Container taller-c01-gate-mlflow-1 Healthy
  descargando t10k-images-idx3-ubyte… (Fashion-MNIST, Zalando Research, licencia MIT)
  descargando t10k-labels-idx1-ubyte… (Fashion-MNIST, Zalando Research, licencia MIT)
  10000 fotos en s3://fotos/ (14.1 MB)
  ds-2026-06-01: {'train': 3263, 'val': 717, 'total': 3980}
  ds-2026-07-01: {'train': 4516, 'val': 999, 'total': 5515}
  ds-2026-08-01: {'train': 5772, 'val': 1265, 'total': 7037}
  ds-2026-09-01: {'train': 6999, 'val': 1524, 'total': 8523}
  golden-v1: 1000 fotos {'chica': 190, 'normal': 600, 'poca_luz': 210} · manifest sha256 0061343ada92…
  entrenando classifier v1 (2026-07) con ds-2026-06-01…
  classifier v1 (2026-07) · val_top1 0.7559 · 21 s
  entrenando classifier v2 (2026-08) con ds-2026-07-01…
  classifier v2 (2026-08) · val_top1 0.8088 · 20 s
  entrenando classifier v3 (2026-09) con ds-2026-08-01…
  classifier v3 (2026-09) · val_top1 0.8395 · 29 s
  entrenando el candidato cand-2026-10-01…
  cand-2026-10-01 · val_top1 0.8675 · 32 s
  entrenando el candidato cand-2026-10-01-proveedor…
  cand-2026-10-01-proveedor · val_top1 0.8360 · 32 s
✓ mundo listo: python verificar.py mundo

git init && git add -A && git commit -m "kit recién descomprimido" · Los ids de commit cambian en cada máquina.

SalidaSalida real · git init && git add -A && git commit -m "kit recién descomprimido"
84a11de kit recién descomprimido
SalidaSalida real · python verificar.py mundo
✓ mundo            S3 local (fotos, ml-datos con 4 snapshots y golden-v1) · MLflow: classifier v1–v3, @champion = v3, 2 candidatos · git

1/1 en verde

¿Ya está corriendo? Elige cómo practicar

las cuatro rondas

Cada ronda se trabaja en una sesión de Claude Code abierta en la carpeta del kit. Copia el prompt de la ronda y pégalo; el enlace de cada tarjeta te lleva a su sección en esta página. El CLAUDE.md del kit pone las reglas de fondo.

ConstruirRomper Con ayuda
1 · Construir con ayudaCon el Guiado de abajo: construyen juntos los pasos 1 a 6. Empieza aquí.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Construir con ayuda**.

Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a escribir juntos, siguiendo los pasos 0 a 6 de `GUION.md`, el gate que decide si el candidato de octubre puede reemplazar al de producción: leer las reglas y los parámetros de esta noche, evaluar a los tres modelos foto por foto sobre el examen congelado, la no inferioridad pareada, las categorías con McNemar y Holm, los slices y la calibración, un gate que frena de verdad y el registro del challenger.

Entre el paso 0 y el 1, `GUION.md` trae los «Precálculos»: las cuentas de servilleta de la estación. Pídeme que haga cada cuenta yo primero, corrígeme y después corre el comando que la comprueba (o dime en qué paso se va a confirmar).

En cada paso:
1. Dime el objetivo en una línea y explícame los conceptos que usa, rápido, con una analogía y con el término en inglés.
2. Escribe conmigo el archivo del paso, por bloques y con el porqué de cada uno. No me pegues el archivo entero de golpe. El contrato de arriba de cada archivo manda.
3. Dime qué comando correr y espera a que te pegue la salida. Los que cambian algo (`pipeline/gate.py`, `pipeline/registrar.py`, `mundo/modelos.py alias`, `git commit`, `git revert`) no los corras tú sin decírmelo antes.
4. Corre `python verificar.py <checks del paso>` y explícame el resultado. Cuando haya una corrida de gate o una versión nueva, ábrela conmigo en MLflow (http://localhost:5500): parámetros, tags, el reporte y los alias.
5. Anota el paso en la bitácora (sección «Bitácora» de `CLAUDE.md`) con lo que hice, lo que medí y lo que sigue.

Si algo falla, no lo arregles en silencio: muéstrame el error, dime tu hipótesis y arreglémoslo juntos. Al final, corre `python verificar.py` completo y cierra la ronda en `taller/progreso.json`.
Ir al Guiado ↓
3 · Romper con ayudaUna falla real; Claude te guía con preguntas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Romper con ayuda**.

Lee `CLAUDE.md`. Todo pasa `python verificar.py`. Ahora:

1. Corre `python romper.py --mostrar` (o `--mostrar --falla <id>` si te digo cuál). El script mete la falla en el mundo, la configuración, el entorno o la infraestructura, nunca en mi pipeline, y te dice cuál fue. **A mí no me la digas.** Solo cuéntame la «historia»: qué notó alguien en el equipo.
2. Corre `python verificar.py` y pregúntame qué veo.
3. Guíame con preguntas en este orden: síntoma → hipótesis (pídeme al menos dos) → el comando que confirma o descarta cada una (`git log -p gate.yaml`, `git log -p corrida.yaml`, `git status`, `python mundo/modelos.py versiones`, `python mundo/modelos.py candidatos`, `python mundo/modelos.py gates`, `python mundo/s3.py golden`, `python mundo/s3.py versiones …`, `docker compose ps`, y mis propios `evaluar.py` y `gate.py`) → el arreglo. Si me atoro más de dos veces en el mismo punto, dame una pista concreta y anótala.
4. Cuando lo arregle, corre `python romper.py --verificar`. Ahí sí explícame qué era, el concepto detrás y cómo se vería en C01 de verdad (el golden set de 50,000 fotos, los umbrales en un PR de ml-catalogo, MLflow con Postgres y S3, el canary que mueve champion).
5. Anota en la bitácora la falla, cuánto tardé, cuántas pistas usé y qué aprendí.

Repetimos con otra falla hasta que te diga que paremos. Para volver al estado sano entre fallas: `python romper.py --restaurar`.
Ir a Romper ↓
Solo
2 · Construir soloRehaces todo desde el esqueleto, solo con los objetivos de Solo.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Construir solo**.

Lee `CLAUDE.md`. **No leas `GUION.md`** ni `mundo/equipo.py`, y no me des código: esta ronda la escribo yo desde el esqueleto, con `OBJETIVOS.md` y los contratos de cada archivo como única guía.

Tu papel:
- Primero corre `python mundo/reiniciar.py --pipeline`: respalda mis archivos en `.respaldo/`, pone el esqueleto (`pipeline/evaluar.py`, `gate.py` y `registrar.py` con su contrato) y borra mis corridas de gate, las versiones que registré, el alias challenger y `reportes/` (el historial del registro, los candidatos y el examen se quedan). Confírmame qué se borró y haz conmigo el commit del esqueleto.
- Cuando te lo pida, corre `python verificar.py` (o un check suelto) y dime qué objetivo pasa y cuál no, con el mensaje exacto.
- Si te pregunto algo, contéstame con una pregunta que me acerque o con el concepto, nunca con el código ni con el arreglo. Si te digo «me rindo en este objetivo», ahí sí explícamelo, y anótalo en la bitácora como pista usada.
- Anota en la bitácora cada objetivo cuando pase: cuánto tardé y qué me costó.

Al final, con `python verificar.py` en verde, cierra la ronda en `taller/progreso.json`.
Ir a Solo ↓
4 · Romper soloUna falla escondida; nadie te da pistas.
Ver el prompt
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 4 de C01, «Gate de evaluación y registry», ronda **Romper solo**.

Lee `CLAUDE.md`. Todo pasa `python verificar.py`.

1. Corre `python romper.py` **sin** `--mostrar`. El script elige una falla al azar y la esconde; tú tampoco sabes cuál es, así que no intentes averiguarla leyendo `romper.py`, `.taller/` ni lo que cambió.
2. Dime solo la «historia» que imprime y la hora de inicio. Desde ahí trabajo yo solo: no me des pistas ni hipótesis. Si te pido correr un comando, córrelo y pégame la salida tal cual, sin interpretarla.
3. Cuando te diga «listo», corre `python romper.py --verificar`. Dime si quedó arreglado, cuál era la falla y cuánto tardé. Si no quedó, dime solo que no y sigo.
4. Si te digo «me rindo», corre `python romper.py --revelar` y explícame la falla completa.
5. Anota en la bitácora la falla, el tiempo, si me rendí y qué haría distinto.
Ir a Romper ↓

Lleva la cuenta en tu tablero: el kit anota tu avance en taller/progreso.json y ahí lo importas.

Guiado

paso a paso

¿Aún no levantas el ambiente? Ve al arranque.

El código que ves es el de la solución de referencia, y cada salida es la que salió al correr el kit en una carpeta limpia.

Precálculos. Antes de escribir el gate, las cuentas de servilleta: cuánto ruido tiene el examen (de ahí sale el margen), qué tan fina es la comparación foto por foto, cuánto ruido tiene una sola categoría, por qué hay que corregir cuando se hacen 10 pruebas a la vez, cuánto pesa la tabla de pares y cuánta erosión se puede colar. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.

1Las reglas y los parámetros de esta nocheSaber, antes de escribir código, contra quién se compara, con qué examen y con qué reglas.

El gate no decide nada que no esté escrito. corrida.yaml trae lo que resolvió el orquestador al arrancar: el candidato y los dos modelos de referencia, por número. gate.yaml trae las reglas: el examen y la huella de su manifest, contra quién se compara y cuánto puede moverse cada cosa. Fíjate en que no dice «el top-1 debe ser 85 %»: dice contra quién y cuánto. Un número absoluto envejece; una comparación contra el que ya está sigue teniendo sentido cada mes.

YAMLgate.yaml
# gate.yaml · las reglas del gate mensual de classifier. Las escribe el equipo ANTES de la corrida y cambian solo en
# un PR propio que otra persona revisa (queda anotado en mundo/revisiones.json). Nunca después de ver un resultado.
# Tu gate.py las lee de aquí: no copies estos números en el código.
examen:
  id: golden-v1                       # el golden set congelado: s3://ml-datos/golden/golden-v1/
  manifest_sha256: 0061343ada92972b0cd41d17ccb17cdd6751e6a3a3296034ad1bae2879355ae9
comparar_contra: [champion, hace_3_meses]   # el de hoy y el de hace 3 meses (la defensa contra la erosión)
top1_top5:
  margen_puntos: 2.4                  # no inferioridad pareada: Δmin ≥ −2.4 puntos. Es el ruido de un modelo solo en
                                      # este examen: 1.96 × √(0.82 × 0.18 ÷ 1,000) × 100 ≈ 2.4 (en C01, con 50,000: 0.3)
categorias:
  caida_max_puntos: 5                 # una categoría está rota si su recall cae más de 5 puntos…
  alfa: 0.05                          # …y la caída es significativa: McNemar por categoría, corregido con Holm
slices:
  nombres: [normal, poca_luz, chica]
  margen_puntos: 5                    # no inferioridad pareada por slice (con ≈ 200 fotos, el ruido es ≈ 5 puntos)
ece_max: 0.05                         # calibración del candidato: error de calibración esperado, 15 cubetas

Del equipo. Sus versiones revisadas están en mundo/revisiones.json: el gate comprueba que la de hoy sea una de ellas.

Terminal
grep -v "^#" corrida.yaml
Salida
candidato: cand-2026-10-01        # la corrida de MLflow que dejó la estación 3
champion: 3                     # classifier@champion al arrancar la corrida
hace_3_meses: 1                 # el champion de julio: la defensa contra la erosión
examen: golden-v1               # el golden set congelado
Terminal
python mundo/modelos.py versiones

El historial del registro: tres meses, cada uno aprobado por su gate.

Salida
v1  —            mes 2026-07 · corrida equipo-2026-07-01 · gate passed · labels.json en orden
v2  —            mes 2026-08 · corrida equipo-2026-08-01 · gate passed · labels.json en orden
v3  @champion    mes 2026-09 · corrida equipo-2026-09-01 · gate passed · labels.json en orden
Terminal
python mundo/modelos.py candidatos

Los dos candidatos de octubre están en el experimento de entrenamiento, sin registrar.

Salida
FINISHED  equipo-2026-07-01            ds-2026-06-01  val_top1 0.7559  pesos 900f8ba1e607
FINISHED  equipo-2026-08-01            ds-2026-07-01  val_top1 0.8088  pesos 6509cf6cab5e
FINISHED  equipo-2026-09-01            ds-2026-08-01  val_top1 0.8395  pesos e858003795ba
FINISHED  cand-2026-10-01              ds-2026-09-01  val_top1 0.8675  pesos 0e36f3a192b0
FINISHED  cand-2026-10-01-proveedor    ds-2026-09-01  val_top1 0.8360  pesos 9abf284a1c20
Terminal
python mundo/s3.py golden
Salida
manifest sha256 0061343ada92972b… · gate.yaml dice 0061343ada92972b… → igual
1000 fotos · slices {'normal': 600, 'chica': 190, 'poca_luz': 210}
por categoría: playeras 103, pantalones 105, sueteres 82, vestidos 99, abrigos 102, sandalias 117, camisas 90, tenis 108, bolsas 99, botines 95
Listo cuando: Puedes decir en voz alta: candidato cand-2026-10-01, contra v3 y v1, con golden-v1 (1,000 fotos, huella 0061343a…) y margen de 2.4 puntos.
Ojo: Las «val_top1» de candidatos son de la validación de cada snapshot, que cambia de mes a mes: no sirven para comparar modelos de meses distintos. Para eso es el examen congelado.
Conceptos de este paso
Gate de evaluaciónevaluation gateUn paso automático del pipeline que decide si un modelo puede avanzar, con reglas escritas antes. Si no se cumplen, el pipeline se detiene.Analogía, por qué importa y la trampa

AnalogíaEl examen de manejo: hay una lista de cosas que tienes que hacer bien, escrita antes de que te subas al coche, y el examinador no la cambia porque le caíste bien.

Por qué importaSin gate, el modelo nuevo llega a producción porque «se ve bien» en una gráfica. Con gate, cada mes se aplica la misma regla, y el historial dice por qué pasó o no pasó cada modelo.

TrampaUn gate que solo mira el promedio global: una categoría rota se esconde detrás de 9 que mejoraron un poco.

Champion y challengerchampion / challengerChampion: el modelo que hoy atiende en producción. Challenger: el que pasó el gate y espera su turno (shadow y canary) para reemplazarlo.Analogía, por qué importa y la trampa

AnalogíaEl campeón de box y el retador: el retador tiene que ganarse la pelea; no basta con decir que está mejor entrenado.

Por qué importaLos dos son alias en el registry, nombres que apuntan a una versión. Cambiar de modelo, o volver atrás, es mover un alias, no reentrenar.

TrampaMover champion a mano «porque ya lo probé en el notebook»: el alias se mueve, pero nadie aprobó ese modelo.

Versión por númeropinned versionEl gate recibe el champion como número (v3), resuelto una sola vez al arrancar, nunca como la pregunta «¿quién es champion?».Analogía, por qué importa y la trampa

AnalogíaComparar contra «el récord de hoy» a media carrera es trampa: el récord puede cambiar mientras corres.

Por qué importaSi el alias se mueve a mitad de la corrida, las predicciones serían de un modelo y el veredicto contra otro. Con el número, el reporte dice exactamente contra quién se comparó.

TrampaRegistrar el veredicto de un gate que comparó contra un champion que ya no es champion: es un veredicto viejo.

Golden set (examen congelado)golden set / frozen test setUn conjunto fijo de fotos con etiquetas revisadas, que ningún entrenamiento ve y que no cambia. Se identifica por su id y por la huella (sha256) de su manifest.Analogía, por qué importa y la trampa

AnalogíaEl metro patrón de París: si cada quien ajusta su metro, ya nadie mide lo mismo.

Por qué importaSolo con el mismo examen se pueden comparar modelos de meses distintos. Si se corrige algo, se publica golden-v2 en un PR propio y todos se vuelven a medir con él.

Trampa«Corregir» unas etiquetas del examen sin cambiarle el nombre: la comparación con los meses anteriores deja de valer y nadie lo nota.

Reglas escritas antespre-registered thresholdsLos umbrales del gate viven en un archivo versionado y cambian solo en un PR propio, revisado por otra persona, antes de la corrida.Analogía, por qué importa y la trampa

AnalogíaLas reglas del partido se acuerdan antes del silbatazo, no al medio tiempo cuando vas perdiendo.

Por qué importaSi se pueden mover después de ver el resultado, cada mes habrá un argumento razonable para aflojar, y el gate deja de medir.

Trampa«Solo por esta vez»: el commit directo a main que afloja una regla para que salga el modelo de la semana.

Precálculo
1

¿De qué tamaño es el margen de no inferioridad?

E = 1.96 × √(q × (1 − q) ÷ N) × 100, en puntos; el margen m es E redondeado
Ver la cuenta
En C01q = 0.85, N = 50,000: 1.96 × √(0.85 × 0.15 ÷ 50,000) × 100≈ 0.31 → m = 0.3 puntos
En el dojoq = 0.82, N = 1,000: 1.96 × √(0.82 × 0.18 ÷ 1,000) × 100≈ 2.38 → m = 2.4 puntos

Qué decides con esto. El margen es lo que el examen ni siquiera puede medir de un modelo solo. Perder menos que eso es perder menos de lo que se ve. Con 1,000 fotos, el dojo solo puede proteger contra pérdidas de más de ≈ 2.4 puntos; C01, con 50,000, contra 0.3. Un examen más grande es un gate más fino.

Terminalterminal · compruébalo en el kit
python -c "
import math
for nombre, q, N in [('C01, golden de 50,000', 0.85, 50000), ('dojo, golden de 1,000', 0.82, 1000)]:
    print(f'{nombre}: E = 1.96 × √({q} × {1 - q:.2f} ÷ {N:,}) × 100 = {196 * math.sqrt(q * (1 - q) / N):.2f} puntos')"
Salida
C01, golden de 50,000: E = 1.96 × √(0.85 × 0.15 ÷ 50,000) × 100 = 0.31 puntos
dojo, golden de 1,000: E = 1.96 × √(0.82 × 0.18 ÷ 1,000) × 100 = 2.38 puntos
2Evaluar a los tres, foto por fotoLas predicciones del candidato, del champion y del de hace 3 meses sobre el mismo examen, comprobando cada huella.

Antes de medir, se comprueba que lo que se mide es lo que se dice: el manifest del examen con la huella de gate.yaml y cada foto con la suya; los pesos de cada modelo con la huella de su corrida; su labels.json contra entrada/categorias.json; y que ninguna foto del examen esté en el snapshot con que se entrenó el candidato. Después, cada foto pasa por el preprocess del gateway y por los tres modelos, y se guarda por foto el top-5 y la confianza de cada uno: los pares.

Pythonpipeline/evaluar.py
"""Paso «evaluar» del gate: el candidato, el champion y el de hace 3 meses, sobre el mismo examen, foto por foto.

    python pipeline/evaluar.py                          # los parámetros de corrida.yaml
    python pipeline/evaluar.py --candidato <corrida>    # otro candidato, con el mismo champion y el mismo examen

Contrato:
- Los modelos entran por NÚMERO de versión (corrida.yaml), nunca por alias: el alias puede moverse a media corrida.
- El examen es golden-v1: su manifest tiene que tener la huella que dice gate.yaml, y cada foto la suya. Si algo no
  coincide, se detiene: un examen que cambió no compara nada.
- Ninguna foto del examen puede estar en el snapshot con que se entrenó el candidato (fuga = examen contaminado).
- Cada modelo: sus pesos tienen la huella que anotó su corrida, y su labels.json es entrada/categorias.json.
- Las fotos pasan por el preprocess del gateway (mundo/gateway/preprocess.py), el mismo de producción.
- Deja reportes/<candidato>/pares.parquet (una fila por foto: label, slice y, por modelo, su top-5 y su confianza)
  y reportes/<candidato>/evaluacion.json (qué se evaluó, con sus huellas).
"""
from __future__ import annotations

import argparse
import io
import json
import sys
import tempfile
from pathlib import Path

import numpy as np
import torch

from _comun import (CLASES, DATOS, EXP_ENTRENAMIENTO, FOTOS, MODELO, REPORTES, corrida, gate, huella_pesos,  # noqa: F401
                    mlflow_cliente, s3, sha256)
from mundo.arquitectura import construir_modelo
from mundo.gateway.preprocess import preprocess

ap = argparse.ArgumentParser()
ap.add_argument("--candidato")
a = ap.parse_args()
cfg, g = corrida(), gate()
candidato = a.candidato or cfg["candidato"]
s = s3()

# 1 · El examen, con sus huellas
examen = g["examen"]
if cfg["examen"] != examen["id"]:
    sys.exit(f"✗ corrida.yaml pide el examen {cfg['examen']} y gate.yaml dice {examen['id']}")
man_b = s.get_object(Bucket=DATOS, Key=f"golden/{examen['id']}/manifest.json")["Body"].read()
if sha256(man_b) != examen["manifest_sha256"]:
    sys.exit(f"✗ el manifest de {examen['id']} cambió: su sha256 es {sha256(man_b)[:12]}… y gate.yaml congeló "
             f"{examen['manifest_sha256'][:12]}…. Un examen que cambió no compara nada: no evalúo")
fotos = json.loads(man_b)["fotos"]
x = []
for f in fotos:
    b = s.get_object(Bucket=DATOS, Key=f["image_key"])["Body"].read()
    if sha256(b) != f["image_sha256"]:
        sys.exit(f"✗ la foto {f['id']} del examen no es la que se congeló (su sha256 no coincide): no evalúo")
    x.append(preprocess(b))
x = torch.from_numpy(np.stack(x))
y = np.array([f["label_id"] for f in fotos])
print(f"[examen] {examen['id']}: {len(fotos)} fotos · manifest {sha256(man_b)[:12]}… = gate.yaml · cada foto con su huella")

# 2 · Los tres modelos, por número, con sus huellas
import mlflow  # noqa: E402

c = mlflow_cliente()
exp = c.get_experiment_by_name(EXP_ENTRENAMIENTO)
rs = c.search_runs([exp.experiment_id], filter_string=f"tags.corrida = '{candidato}' and attributes.status = 'FINISHED'", max_results=1)
if not rs:
    sys.exit(f"✗ no hay una corrida terminada que se llame {candidato} en {EXP_ENTRENAMIENTO}")
run_cand = rs[0]


def cargar(run_id: str, quien: str, huella: str | None):
    with tempfile.TemporaryDirectory() as d:
        carpeta = Path(mlflow.artifacts.download_artifacts(run_id=run_id, artifact_path="modelo", dst_path=d))
        pesos = torch.load(carpeta / "pesos.pt", map_location="cpu", weights_only=True)
        labels = json.loads((carpeta / "labels.json").read_text())
    if labels != CLASES:
        sys.exit(f"✗ el labels.json de {quien} no es entrada/categorias.json ({labels[:3]}…): la salida 0 no sería «{CLASES[0]}»")
    if huella_pesos(pesos) != huella:
        sys.exit(f"✗ los pesos de {quien} no tienen la huella que anotó su corrida: no sé qué estoy evaluando")
    m = construir_modelo(len(CLASES))
    m.load_state_dict(pesos)
    return m.eval(), huella


modelos = {"candidato": cargar(run_cand.info.run_id, candidato, run_cand.data.tags.get("pesos_sha256"))}
versiones = {"candidato": None}
for quien in ("champion", "hace_3_meses"):
    v = str(cfg[quien])
    if not v.isdigit():
        sys.exit(f"✗ corrida.yaml: {quien} = {v}. Entra como número de versión, no como alias")
    mv = c.get_model_version(MODELO, v)
    modelos[quien] = cargar(mv.run_id, f"{MODELO} v{v}", mv.tags.get("pesos_sha256"))
    versiones[quien] = v
print(f"[modelos] {candidato} · champion = v{versiones['champion']} · hace 3 meses = v{versiones['hace_3_meses']} · "
      "pesos con su huella y labels.json en orden")

# 3 · Fuga: ¿alguna foto del examen está en el snapshot del candidato?
sid = run_cand.data.tags["snapshot"]
import pandas as pd  # noqa: E402

filas = pd.read_parquet(io.BytesIO(s.get_object(Bucket=DATOS, Key=f"datasets/{sid}/rows.parquet")["Body"].read()))
vistas = set(filas["image_sha256"])
fuga = sum(f["origen_sha256"] in vistas or f["image_sha256"] in vistas for f in fotos)
if fuga:
    sys.exit(f"✗ {fuga} fotos del examen están en {sid}, el snapshot con que se entrenó {candidato}: el examen está "
             "contaminado y el candidato saldría mejor de lo que es. No evalúo")
print(f"[fuga] 0 de {len(fotos)} fotos del examen están en {sid} ({len(filas):,} filas)")

# 4 · Las predicciones, foto por foto
pares = pd.DataFrame({"id": [f["id"] for f in fotos], "label_id": y, "slice": [f["slice"] for f in fotos]})
with torch.no_grad():
    for quien, (m, _) in modelos.items():
        p = torch.softmax(m(x), 1).numpy()
        top5 = np.argsort(-p, 1, kind="stable")[:, :5]
        pares[f"{quien}_top5"] = top5.tolist()
        pares[f"{quien}_conf"] = p.max(1)
        print(f"  {quien:<13} top-1 {np.mean(top5[:, 0] == y):.2%} · top-5 {np.mean((top5 == y[:, None]).any(1)):.2%}")

out = REPORTES / candidato
out.mkdir(parents=True, exist_ok=True)
pares.to_parquet(out / "pares.parquet", index=False)
(out / "evaluacion.json").write_text(json.dumps({
    "candidato": candidato, "candidato_run_id": run_cand.info.run_id, "snapshot": sid,
    "champion_version": versiones["champion"], "hace_3_meses_version": versiones["hace_3_meses"],
    "pesos_sha256": {k: v[1] for k, v in modelos.items()},
    "examen": examen["id"], "manifest_sha256": sha256(man_b), "fuga": fuga,
    "pares_sha256": sha256((out / "pares.parquet").read_bytes())}, ensure_ascii=False, indent=2) + "\n")
print(f"✓ {len(pares)} pares en reportes/{candidato}/pares.parquet")

Cada sys.exit es una razón para no evaluar: un examen que cambió, unos pesos que no son los anotados, unas categorías en otro orden o una fuga.

Terminal
python pipeline/evaluar.py
Salida
[examen] golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · cada foto con su huella
[modelos] cand-2026-10-01 · champion = v3 · hace 3 meses = v1 · pesos con su huella y labels.json en orden
[fuga] 0 de 1000 fotos del examen están en ds-2026-09-01 (8,523 filas)
  candidato     top-1 83.20% · top-5 99.70%
  champion      top-1 81.70% · top-5 99.50%
  hace_3_meses  top-1 73.80% · top-5 99.00%
✓ 1000 pares en reportes/cand-2026-10-01/pares.parquet
Terminal
python -c "import pandas as pd; print(pd.read_parquet('reportes/cand-2026-10-01/pares.parquet').head(3))"

Una fila por foto: su etiqueta, su slice y, por modelo, su top-5 y su confianza.

Salida
(1000, 9) · 36 kB
       id  label_id   slice   candidato_top5  candidato_conf    champion_top5  champion_conf hace_3_meses_top5  hace_3_meses_conf
0  g-0001         1  normal  [1, 3, 4, 5, 2]        0.998052  [1, 3, 4, 5, 2]       0.999548   [1, 3, 5, 4, 6]           0.965537
1  g-0002         4   chica  [6, 4, 2, 0, 8]        0.525149  [6, 4, 2, 8, 0]       0.428078   [6, 2, 4, 8, 0]           0.396477
2  g-0003         8   chica  [8, 0, 9, 6, 2]        0.993680  [8, 9, 2, 0, 6]       0.994068   [8, 9, 4, 0, 6]           0.946153
Terminal
python verificar.py examen pares labels
Salida
✓ examen           golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · 0 fotos del examen en ds-2026-09-01
✓ pares            1000 pares · top-1 en golden-v1: candidato 83.2 %, champion v3 81.7 %, hace 3 meses v1 73.8 % · 20/20 predicciones del champion recalculadas iguales
✓ labels           el labels.json de las 3 versiones y del candidato = entrada/categorias.json (sha 97864728052c…)

3/3 en verde
Listo cuando: 1,000 pares; top-1 en el examen: candidato 83.20 %, champion 81.70 %, hace 3 meses 73.80 %; 20 predicciones del champion recalculadas iguales.
Ojo: Sin model.eval(), la BatchNorm usa las estadísticas de cada lote y las predicciones cambian según con qué otras fotos venga cada una.
Conceptos de este paso
Evaluación pareadapaired evaluationLos dos modelos responden las mismas fotos y se comparan foto por foto: b = solo el nuevo acierta, c = solo el viejo acierta.Analogía, por qué importa y la trampa

AnalogíaDos cocineros preparan los mismos 1,000 platillos; para saber quién es mejor, solo importan los platillos en que uno acertó y el otro no.

Por qué importaLas fotos fáciles (los dos aciertan) y las imposibles (los dos fallan) no dicen nada; solo las discrepancias. Por eso la comparación pareada es más fina que comparar dos promedios.

TrampaGuardar solo «83.2 % vs 81.7 %»: sin los pares no hay prueba pareada, ni categorías, ni slices.

Fuga hacia el examendata leakage / test contaminationQue fotos del examen terminen en los datos de entrenamiento. El modelo ya vio las respuestas: sale mejor en el examen sin ser mejor.Analogía, por qué importa y la trampa

AnalogíaEstudiar con el examen que te van a poner: sacas 10 y no aprendiste nada.

Por qué importaEl gate cruza las huellas del snapshot del candidato con las del examen y se detiene si hay una sola en común. La estación 2 deja el golden set fuera por diseño.

TrampaCelebrar un candidato que «sube 3 puntos» sin preguntar con qué datos se entrenó.

labels.json: el orden es parte del modelolabel mapLa lista que dice qué categoría es cada salida de la red: la salida 0 es «playeras», la 1 «pantalones»… Viaja con los pesos y se registra con su huella.Analogía, por qué importa y la trampa

AnalogíaLas etiquetas de los frascos de la cocina: si las revuelves, el azúcar sigue siendo azúcar, pero le pones sal al café.

Por qué importaCon otro orden, los números del gate salen iguales (se evalúa por índice) y el gateway muestra otra categoría. Solo se nota si se compara el labels.json, o cuando cae la aceptación.

TrampaOrdenar las categorías alfabéticamente «para que se vea limpio».

Precálculo
5

¿Cuánto pesa guardar las predicciones foto por foto?

filas = modelos × fotos; cada fila, el top-5 y la confianza
Ver la cuenta
En C013 modelos × 50,000 fotos = 150,000 filas≈ 5–10 MB en Parquet
En el dojo1,000 fotos, una fila con las 3 columnas de cada modelo≈ 36 kB

Qué decides con esto. Guardar los pares es casi gratis, y sin ellos no hay prueba pareada, ni categorías, ni slices: solo dos promedios que no dicen en qué fotos discrepan. Se guardan siempre, con la corrida del gate.

Lo confirmas en el paso 2: reportes/cand-2026-10-01/pares.parquet pesa ≈ 36 kB.

3No inferioridad pareada, con reglas revisadasEl candidato no es peor que v3 ni que v1 por más de 2.4 puntos, en top-1 y en top-5, y las reglas son las aprobadas.

Primero, el gate comprueba sus propias reglas: gate.yaml en un commit y con una huella revisada. Después cuenta, contra cada modelo de comparar_contra, las fotos donde solo acierta el nuevo (b) y solo el otro (c): Δ = (b − c) ÷ N × 100, SE = √(b + c) ÷ N × 100 y Δmin = Δ − 1.96 × SE. Pasa si Δmin ≥ −2.4. Contra el de hace 3 meses es la misma regla: así se ataja la erosión.

Pythonpipeline/gate.py
# 1 · Las reglas: revisadas y en un commit
if git("status", "--porcelain", "--", "gate.yaml", "corrida.yaml"):
    sys.exit("✗ gate.yaml o corrida.yaml tienen cambios sin commit: el veredicto no podría decir con qué reglas se tomó")
gate_sha = sha256((RAIZ / "gate.yaml").read_bytes())
if gate_sha not in {r["gate_yaml_sha256"] for r in revisiones()}:
    sys.exit(f"✗ gate.yaml ({gate_sha[:12]}…) no es ninguna versión revisada de mundo/revisiones.json: alguien cambió las "
             "reglas sin PR. No juzgo con reglas que nadie aprobó")

# 2 · Los pares de esta corrida
carpeta = REPORTES / candidato
ev = json.loads((carpeta / "evaluacion.json").read_text())
if str(ev["champion_version"]) != str(cfg["champion"]) or ev["examen"] != g["examen"]["id"]:
    sys.exit(f"✗ los pares de {candidato} son contra champion v{ev['champion_version']} con {ev['examen']}, y esta corrida pide "
             f"v{cfg['champion']} con {g['examen']['id']}: vuelve a correr evaluar.py")
if sha256((carpeta / "pares.parquet").read_bytes()) != ev["pares_sha256"]:
    sys.exit("✗ pares.parquet no es el que dejó evaluar.py (su huella cambió)")
p = pd.read_parquet(carpeta / "pares.parquet")
y, N = p["label_id"].to_numpy(), len(p)


def acierta(quien: str, k: int) -> np.ndarray:
    return np.array([t in top[:k] for t, top in zip(y, p[f"{quien}_top5"])])


def pareada(nuevo: np.ndarray, viejo: np.ndarray, margen: float) -> dict:
    b, c, n = int((nuevo & ~viejo).sum()), int((~nuevo & viejo).sum()), len(nuevo)
    d, se = (b - c) / n * 100, math.sqrt(b + c) / n * 100
    return {"b": b, "c": c, "n": n, "delta": round(d, 4), "se": round(se, 4), "delta_min": round(d - 1.96 * se, 4),
            "pasa": bool(d - 1.96 * se >= -margen)}


def mcnemar(b: int, c: int) -> float:
    """McNemar exacto, de dos colas: si los dos modelos fueran igual de buenos, cada discrepancia es un volado."""
    n = b + c
    return 1.0 if n == 0 else min(1.0, 2 * sum(math.comb(n, i) for i in range(min(b, c) + 1)) / 2 ** n)


motivos, r = [], {"candidato": candidato, "champion_version": ev["champion_version"],
                  "hace_3_meses_version": ev["hace_3_meses_version"], "examen": ev["examen"], "gate_yaml_sha256": gate_sha}

# 3 · No inferioridad, top-1 y top-5, contra cada modelo de comparar_contra
m = g["top1_top5"]["margen_puntos"]
r["no_inferioridad"] = {}
for ref in g["comparar_contra"]:
    for k in (1, 5):
        x = pareada(acierta("candidato", k), acierta(ref, k), m)
        r["no_inferioridad"][f"{ref}_top{k}"] = x
        print(f"[no inferioridad] vs {ref:<12} top-{k}: b {x['b']:>3} · c {x['c']:>3} · Δ {x['delta']:+.2f} · "
              f"SE {x['se']:.2f} · Δmin {x['delta_min']:+.2f} {'≥' if x['pasa'] else '<'} −{m} → {'pasa' if x['pasa'] else 'NO PASA'}")
        if not x["pasa"]:
            motivos.append(f"top-{k} contra {ref}: Δmin {x['delta_min']:+.2f} < −{m}")

Las funciones acierta() y pareada() sirven también para categorías y slices.

Terminal
sed -i '' 's/margen_puntos: 2.4 /margen_puntos: 3.0 /' gate.yaml
python pipeline/gate.py

Una prueba: mover el margen sin commit.

Salida
✗ gate.yaml o corrida.yaml tienen cambios sin commit: el veredicto no podría decir con qué reglas se tomó
[código 1]
Terminal
git commit -qam "gate: margen 3.0 (prueba)"
python pipeline/gate.py

En un commit, pero sin revisión: tampoco.

Salida
✗ gate.yaml (d4d7fc2aa33b…) no es ninguna versión revisada de mundo/revisiones.json: alguien cambió las reglas sin PR. No juzgo con reglas que nadie aprobó
[código 1]
Terminal
git revert --no-edit HEAD
python pipeline/gate.py

Con las reglas revisadas de vuelta.

Salida
[no inferioridad] vs champion     top-1: b  38 · c  23 · Δ +1.50 · SE 0.78 · Δmin -0.03 ≥ −2.4 → pasa
[no inferioridad] vs champion     top-5: b   2 · c   0 · Δ +0.20 · SE 0.14 · Δmin -0.08 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-1: b 128 · c  34 · Δ +9.40 · SE 1.27 · Δmin +6.91 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-5: b   8 · c   1 · Δ +0.70 · SE 0.30 · Δmin +0.11 ≥ −2.4 → pasa
[categorías] la que más cae: playeras 87.4 → 84.5 (b 1 · c 4 · p de Holm 1) · rotas: ninguna
[slice] normal    n 600 · Δ -0.50 · Δmin -2.26 → pasa
[slice] poca_luz  n 210 · Δ +4.76 · Δmin +0.59 → pasa
[slice] chica     n 190 · Δ +4.21 · Δmin +0.64 → pasa
[calibración] ECE 0.0238 ≤ 0.05
✓ PASA: cand-2026-10-01 es no inferior a v3 y a v1 · corrida gate-cand-2026-10-01
Terminal
python verificar.py no-inferioridad umbrales
Salida
✓ no-inferioridad  vs champion: b 38 · c 23 · Δmin -0.03 · vs hace_3_meses: b 128 · c 34 · Δmin +6.91 (margen −2.4, top-5 también)
✓ umbrales         gate.yaml = la revisión del PR #41 (2026-07-01) · sin cambios pendientes · 1 gate(s), todos con reglas revisadas

2/2 en verde
Listo cuando: Contra v3: b = 38, c = 23, Δmin = -0.03 ≥ −2.4. Contra v1 pasa con holgura. Y el gate se negó a correr con un gate.yaml sin commit o sin revisión.
Ojo: El candidato acierta 1.5 puntos más que el champion y aun así su Δmin es -0.03: con 61 discrepancias, el examen no puede asegurar que sea mejor, solo que no es peor. Para un reentrenamiento mensual, eso basta.
Conceptos de este paso
No inferioridadnon-inferiority testPedir que el modelo nuevo no sea peor que el actual por más de un margen, con buena seguridad. No se le pide ganar.Analogía, por qué importa y la trampa

AnalogíaUn medicamento genérico más barato: no tiene que curar más que el original, solo no curar menos por más de un margen chico.

Por qué importaEl reentrenamiento mensual busca estar al día, no ganar. Exigir «mejor de forma significativa» bloquearía casi todos los meses; exigir «≥ champion» decidiría con una moneda.

TrampaMirar el centro (Δ) en vez del extremo de abajo (Δmin): un Δ de −0.5 puede pasar o no según cuánto ruido haya.

Margen de no inferioridadnon-inferiority marginCuánto se acepta que el modelo nuevo pierda contra el actual. Se fija antes, del tamaño del ruido del examen: lo que el examen ni siquiera puede medir.Analogía, por qué importa y la trampa

AnalogíaLa tolerancia de una báscula: si mide de ± 100 g, no tiene caso discutir por 50.

Por qué importaEn C01, 0.3 puntos (golden de 50,000). En el dojo, 2.4 (golden de 1,000). Es una decisión de negocio vestida de estadística: en C01, con ≈ 10 millones de fotos al día, 0.3 puntos son ≈ 30,000 primeras sugerencias equivocadas más al día.

TrampaElegirlo después de ver el resultado. Entonces ya no mide: justifica.

Error estándar e intervalostandard error / confidence intervalSE_Δ dice cuánto se movería la diferencia por azar con otras fotos. Δmin = Δ − 1.96 × SE es el extremo de abajo del intervalo de 95 %: lo peor que puede ser, con buena seguridad.Analogía, por qué importa y la trampa

AnalogíaEl margen de error de una encuesta: «42 % ± 3» quiere decir que lo real está, casi seguro, entre 39 y 45.

Por qué importaLa regla del gate es Δmin ≥ −margen. Con pocas discrepancias el intervalo es estrecho; con muchas, ancho.

TrampaConfundir el SE de un modelo solo (el del margen) con el SE pareado (el de la diferencia): el segundo es más chico.

Erosión de calidadslow regressionPerder un poco cada mes, siempre dentro del margen: cada comparación pasa, y la suma de un año es grande.Analogía, por qué importa y la trampa

AnalogíaLa rana en el agua que se calienta despacio: ningún grado de más se nota, la suma sí.

Por qué importaPor eso el gate compara también contra el champion de hace 3 meses: contra él se suman tres meses de pérdida, que no caben en el margen.

TrampaComparar solo contra el mes anterior y creer que eso protege del largo plazo.

Precálculos
2

¿Qué tan fina es la comparación foto por foto?

SE_Δ = √(b + c) ÷ N × 100, donde b + c son las fotos en que los dos modelos discrepan
Ver la cuenta
En C012,100 discrepancias de 50,000: √2,100 ÷ 50,000 × 100≈ 0.09 puntos (intervalo ± 0.18)
En el dojo61 discrepancias de 1,000 (b = 38, c = 23): √61 ÷ 1,000 × 100≈ 0.78 puntos (intervalo ± 1.53)

Qué decides con esto. Las fotos que los dos aciertan o los dos fallan no mueven la diferencia: solo cuentan las que discrepan. Por eso la comparación pareada es más fina que el margen y el gate puede leer pérdidas más chicas que el ruido de un modelo solo.

Lo confirmas en el paso 3: contra el champion salen b = 38 y c = 23, SE = 0.78.

6

¿Cuánta erosión se cuela si solo comparas contra el champion?

cada mes pasa si la pérdida r cumple r + 1.96 × SE_Δ ≤ m; en 12 meses se acumulan 12 × r
Ver la cuenta
En C01r = 0.2 puntos al mes, SE_Δ ≈ 0.045: cada mes pasa; 12 × 0.22.4 puntos al año, sin un solo gate en rojo
En el dojom = 2.4, SE_Δ ≈ 0.78: pasa cada mes cualquier r ≤ 2.4 − 1.96 × 0.78≈ 0.9 puntos al mes

Qué decides con esto. Por eso el gate también compara contra el champion de hace 3 meses, con la misma regla: contra él se suman tres meses de pérdida, que ya no caben en el margen.

Lo confirmas en el paso 3: contra el de hace 3 meses (v1) el candidato está +9.4 puntos arriba; aquí no hubo erosión.

4Categorías, slices y calibraciónNinguna categoría rota, ningún slice abajo de su margen y la confianza del candidato calibrada.

Un promedio que no baja puede esconder una categoría rota. Por categoría, el gate pide dos cosas para declararla rota: que el recall caiga más de 5 puntos y que la caída sea significativa (McNemar con las discrepancias de esa categoría, corregido con Holm porque son 10 pruebas). Por slice, la misma no inferioridad pareada con un margen de 5 puntos (con ≈ 200 fotos, el ruido es de ese tamaño). Y la calibración: el ECE del candidato, con 15 cubetas de confianza, ≤ 0.05. Todo va al reporte y a una corrida de MLflow; si algo falla, la corrida queda FAILED y el proceso sale con código 1.

Pythonpipeline/gate.py
# 4 · Por categoría: caída grande Y significativa (McNemar + Holm)
cg = g["categorias"]
nuevo, viejo = acierta("candidato", 1), acierta("champion", 1)
cats = []
for i, nombre in enumerate(CLASES):
    s = y == i
    b, c = int((nuevo & ~viejo & s).sum()), int((~nuevo & viejo & s).sum())
    cats.append({"categoria": nombre, "n": int(s.sum()), "recall_candidato": round(nuevo[s].mean() * 100, 2),
                 "recall_champion": round(viejo[s].mean() * 100, 2), "caida": round((viejo[s].mean() - nuevo[s].mean()) * 100, 2),
                 "b": b, "c": c, "p": mcnemar(b, c)})
orden = sorted(range(len(cats)), key=lambda i: cats[i]["p"])      # Holm: la p más chica contra α/10, la siguiente contra α/9…
maximo = 0.0
for rango, i in enumerate(orden):
    maximo = max(maximo, min(1.0, cats[i]["p"] * (len(cats) - rango)))   # p ajustada, nunca menor que la anterior
    cats[i]["p_holm"] = maximo
for x in cats:
    x["rota"] = bool(x["caida"] > cg["caida_max_puntos"] and x["p_holm"] < cg["alfa"])
    if x["rota"]:
        motivos.append(f"categoría {x['categoria']}: recall {x['recall_champion']:.1f} → {x['recall_candidato']:.1f} "
                       f"(−{x['caida']:.1f} puntos, p de Holm {x['p_holm']:.2g})")
r["categorias"] = cats
peor = max(cats, key=lambda x: x["caida"])
print(f"[categorías] la que más cae: {peor['categoria']} {peor['recall_champion']:.1f} → {peor['recall_candidato']:.1f} "
      f"(b {peor['b']} · c {peor['c']} · p de Holm {peor['p_holm']:.2g}) · rotas: {[x['categoria'] for x in cats if x['rota']] or 'ninguna'}")

# 5 · Slices
r["slices"] = {}
for nombre in g["slices"]["nombres"]:
    s = (p["slice"] == nombre).to_numpy()
    x = pareada(nuevo[s], viejo[s], g["slices"]["margen_puntos"])
    r["slices"][nombre] = x
    print(f"[slice] {nombre:<9} n {x['n']:>3} · Δ {x['delta']:+.2f} · Δmin {x['delta_min']:+.2f} → {'pasa' if x['pasa'] else 'NO PASA'}")
    if not x["pasa"]:
        motivos.append(f"slice {nombre}: Δmin {x['delta_min']:+.2f} < −{g['slices']['margen_puntos']}")

# 6 · Calibración: ¿su confianza dice la verdad?
conf = p["candidato_conf"].to_numpy()
cubeta = np.minimum((conf * 15).astype(int), 14)
ece = sum((cubeta == k).sum() / N * abs(nuevo[cubeta == k].mean() - conf[cubeta == k].mean()) for k in range(15) if (cubeta == k).any())
r["ece"] = round(float(ece), 4)
print(f"[calibración] ECE {ece:.4f} {'≤' if ece <= g['ece_max'] else '>'} {g['ece_max']}")
if ece > g["ece_max"]:
    motivos.append(f"ECE {ece:.4f} > {g['ece_max']}")

# 7 · El veredicto: en el reporte, en MLflow y en el código de salida
r["veredicto"], r["motivos"] = ("pasa" if not motivos else "no_pasa"), motivos
r["top1"] = {q: round(acierta(q, 1).mean() * 100, 2) for q in ("candidato", "champion", "hace_3_meses")}
(carpeta / "reporte.json").write_text(json.dumps(r, ensure_ascii=False, indent=2) + "\n")

import mlflow  # noqa: E402

c = mlflow_cliente()
if not c.get_experiment_by_name(EXP_GATE):
    c.create_experiment(EXP_GATE)
mlflow.set_experiment(EXP_GATE)
with mlflow.start_run(run_name=f"gate-{candidato}") as run:
    mlflow.log_params({"candidato": candidato, "champion_version": ev["champion_version"], "hace_3_meses_version": ev["hace_3_meses_version"],
                       "examen": ev["examen"], "margen_puntos": m})
    mlflow.log_metrics({f"delta_min_{k}": v["delta_min"] for k, v in r["no_inferioridad"].items()} | {"ece": r["ece"]} |
                       {f"top1_{q}": v for q, v in r["top1"].items()})
    mlflow.set_tags({"candidato": candidato, "candidato_run_id": ev["candidato_run_id"], "champion_version": str(ev["champion_version"]),
                     "examen": ev["examen"], "manifest_sha256": ev["manifest_sha256"], "gate_yaml_sha256": gate_sha,
                     "commit": git("rev-parse", "HEAD"), "veredicto": r["veredicto"], "motivo": "; ".join(motivos)[:4000] or "—"})
    mlflow.log_artifacts(str(carpeta), "reporte")
    if motivos:
        mlflow.end_run("FAILED")
if motivos:
    sys.exit("✗ NO PASA: " + " · ".join(motivos))
print(f"✓ PASA: {candidato} es no inferior a v{ev['champion_version']} y a v{ev['hace_3_meses_version']} · corrida gate-{candidato}")

El último bloque decide: el veredicto va al reporte, a MLflow y al código de salida. sys.exit con un mensaje sale con código 1.

Terminal
python pipeline/gate.py      # la misma corrida del paso 3
Salida
[categorías] la que más cae: playeras 87.4 → 84.5 (b 1 · c 4 · p de Holm 1) · rotas: ninguna
[slice] normal    n 600 · Δ -0.50 · Δmin -2.26 → pasa
[slice] poca_luz  n 210 · Δ +4.76 · Δmin +0.59 → pasa
[slice] chica     n 190 · Δ +4.21 · Δmin +0.64 → pasa
[calibración] ECE 0.0238 ≤ 0.05
✓ PASA: cand-2026-10-01 es no inferior a v3 y a v1 · corrida gate-cand-2026-10-01
Terminal
python -c "
import json
r = json.load(open('reportes/cand-2026-10-01/reporte.json'))
for x in r['categorias']:
    print(x['categoria'], x['n'], x['recall_champion'], '→', x['recall_candidato'], x['b'], x['c'], x['p'], x['p_holm'])"

Las 10 categorías del reporte (la salida es la del script de prueba, con columnas alineadas).

Salida
playeras   n 103 ·  87.4 →  84.5 · b  1 · c  4 · p 0.375 · Holm 1.000
pantalones n 105 ·  95.2 →  96.2 · b  2 · c  1 · p 1.000 · Holm 1.000
sueteres   n  82 ·  79.3 →  76.8 · b  3 · c  5 · p 0.727 · Holm 1.000
vestidos   n  99 ·  75.8 →  79.8 · b  5 · c  1 · p 0.219 · Holm 1.000
abrigos    n 102 ·  65.7 →  66.7 · b  6 · c  5 · p 1.000 · Holm 1.000
sandalias  n 117 ·  89.7 →  92.3 · b  5 · c  2 · p 0.453 · Holm 1.000
camisas    n  90 ·  34.4 →  47.8 · b 13 · c  1 · p 0.002 · Holm 0.018
tenis      n 108 ·  95.4 →  96.3 · b  1 · c  0 · p 1.000 · Holm 1.000
bolsas     n  99 ·  93.9 →  93.9 · b  1 · c  1 · p 1.000 · Holm 1.000
botines    n  95 ·  92.6 →  90.5 · b  1 · c  3 · p 0.625 · Holm 1.000
Terminal
python verificar.py categorias slices
Salida
✓ categorias       10 categorías con McNemar + Holm · la que más cae: playeras (+2.9 puntos, p de Holm 1) · rotas: ninguna
✓ slices           Δmin por slice: normal -2.26, poca_luz +0.59, chica +0.64 (margen −5) · ECE 0.0238 ≤ 0.05

2/2 en verde
Listo cuando: 10 categorías con McNemar y Holm, ninguna rota; los tres slices dentro de su margen; ECE ≤ 0.05.
Ojo: Camisas sube 13 puntos y su p es chica: McNemar también detecta mejoras. La regla solo frena caídas.
Conceptos de este paso
Prueba de McNemarMcNemar's testPara dos modelos sobre las mismas fotos: si fueran igual de buenos, cada discrepancia sería un volado. La prueba da la probabilidad (p) de ver un reparto tan desigual de b y c por azar.Analogía, por qué importa y la trampa

AnalogíaSi una moneda sale 21 veces cruz y 2 águila, sospechas que está cargada: es muy raro por azar.

Por qué importaSepara una categoría rota (camisas: 2 contra 21) del ruido (playeras: 1 contra 4). Usa solo las discrepancias de esa categoría.

TrampaUsarla con muy pocas discrepancias y concluir «no hay diferencia»: con 3 discrepancias, ninguna prueba puede ver nada.

Corrección de HolmHolm–Bonferroni correctionAl hacer k pruebas a la vez, ordena las p de menor a mayor y compara la primera contra α/k, la segunda contra α/(k − 1)… Así la falsa alarma de todo el conjunto queda en α.Analogía, por qué importa y la trampa

AnalogíaSi compras 10 boletos de lotería, ganar uno ya no es tan sorprendente: hay que pedir más para creer que no fue suerte.

Por qué importaCon 10 categorías y α = 0.05 sin corregir, ≈ 40 % de los meses alguna «cae» por azar y el gate frena a un modelo sano.

TrampaNo corregir porque «cada prueba es al 5 %»: el 5 % es por prueba, no por gate.

Slicedata sliceUn pedazo del examen con algo en común: fotos con poca luz, fotos chicas, fotos del celular. Se evalúa aparte porque un promedio lo puede esconder.Analogía, por qué importa y la trampa

AnalogíaUn restaurante con 4.5 estrellas que da intoxicación los martes: el promedio no lo dice, el corte por día sí.

Por qué importaEl candidato del proveedor no se ve tan mal en global (−1.3 puntos) y en poca luz su Δmin cae a −5.5: ahí es donde más se nota el lote malo.

TrampaUsar el margen global en un slice chico: con 200 fotos el ruido es ≈ 5 puntos, y el gate se pondría en rojo por azar.

Calibración (ECE)calibration / expected calibration errorSi el modelo dice «90 % seguro», ¿acierta 9 de cada 10? El ECE agrupa las fotos por confianza y promedia la distancia entre confianza y aciertos.Analogía, por qué importa y la trampa

AnalogíaUn pronóstico del clima que dice «70 % de lluvia» y llueve 7 de cada 10 de esos días está bien calibrado.

Por qué importaProducto usa la confianza (por ejemplo, para pedir revisión humana debajo de un umbral). Un modelo que acierta igual pero dice «99 %» siempre rompe esa regla.

TrampaMirar solo la exactitud: dos modelos con el mismo top-1 pueden tener calibraciones muy distintas.

Precálculos
3

¿Cuánto ruido tiene el recall de una sola categoría?

E = 1.96 × √(r × (1 − r) ÷ n) × 100, con n las fotos de esa categoría
Ver la cuenta
En C01una de las 100 grandes, con ≈ 500 fotos y r = 0.85: 1.96 × √(0.85 × 0.15 ÷ 500) × 100≈ 3.1 puntos
En el dojo≈ 100 fotos por categoría y r = 0.85: 1.96 × √(0.85 × 0.15 ÷ 100) × 100≈ 7 puntos

Qué decides con esto. Una caída de 5 puntos en una categoría puede ser azar. Por eso la regla pide dos cosas: que caiga más de 5 puntos y que la caída sea significativa con McNemar, que usa los pares de esa categoría.

Terminalterminal · compruébalo en el kit
python -c "
import math
print(f'una categoría con 100 fotos y recall 0.85: E = 1.96 × √(0.85 × 0.15 ÷ 100) × 100 = {196 * math.sqrt(0.85 * 0.15 / 100):.1f} puntos')"
Salida
una categoría con 100 fotos y recall 0.85: E = 1.96 × √(0.85 × 0.15 ÷ 100) × 100 = 7.0 puntos
4

Si haces 10 pruebas a la vez, ¿cuántas falsas alarmas esperas?

P(al menos una falsa alarma) = 1 − (1 − α)^k, con k pruebas y α = 0.05
Ver la cuenta
En C01100 categorías: 1 − 0.95^100≈ 99 %
En el dojo10 categorías: 1 − 0.95^10≈ 40 %

Qué decides con esto. Sin corregir, el gate frenaría a un modelo sano casi siempre: con 10 pruebas, 4 de cada 10 meses alguna «cae» por azar. La corrección de Holm vuelve a dejar la falsa alarma del gate completo en 5 %.

Terminalterminal · compruébalo en el kit
python -c "
for k in (10, 100):
    print(f'{k} pruebas con α = 0.05 y ninguna diferencia real: P(al menos una falsa alarma) = 1 − 0.95^{k} = {1 - 0.95 ** k:.1%}')"
Salida
10 pruebas con α = 0.05 y ninguna diferencia real: P(al menos una falsa alarma) = 1 − 0.95^10 = 40.1%
100 pruebas con α = 0.05 y ninguna diferencia real: P(al menos una falsa alarma) = 1 − 0.95^100 = 99.4%
5El gate que frenaEl candidato del proveedor no pasa, la corrida queda en rojo y el motivo dice por qué.

El segundo candidato de octubre se entrenó con un lote del proveedor que etiquetó como «playeras» casi la mitad de las camisas. Se evalúa con el mismo champion y el mismo examen. El gate no «devuelve false»: termina con código 1 y su corrida en MLflow queda FAILED, con el motivo. Así el orquestador no sigue a los pasos de después y la alerta de pipeline fallido avisa a alguien.

Terminal
python pipeline/evaluar.py --candidato cand-2026-10-01-proveedor
Salida
[examen] golden-v1: 1000 fotos · manifest 0061343ada92… = gate.yaml · cada foto con su huella
[modelos] cand-2026-10-01-proveedor · champion = v3 · hace 3 meses = v1 · pesos con su huella y labels.json en orden
[fuga] 0 de 1000 fotos del examen están en ds-2026-09-01 (8,523 filas)
  candidato     top-1 80.40% · top-5 99.70%
  champion      top-1 81.70% · top-5 99.50%
  hace_3_meses  top-1 73.80% · top-5 99.00%
✓ 1000 pares en reportes/cand-2026-10-01-proveedor/pares.parquet
Terminal
python pipeline/gate.py --candidato cand-2026-10-01-proveedor
Salida
[no inferioridad] vs champion     top-1: b  32 · c  45 · Δ -1.30 · SE 0.88 · Δmin -3.02 < −2.4 → NO PASA
[no inferioridad] vs champion     top-5: b   2 · c   0 · Δ +0.20 · SE 0.14 · Δmin -0.08 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-1: b 110 · c  44 · Δ +6.60 · SE 1.24 · Δmin +4.17 ≥ −2.4 → pasa
[no inferioridad] vs hace_3_meses top-5: b   8 · c   1 · Δ +0.70 · SE 0.30 · Δmin +0.11 ≥ −2.4 → pasa
[categorías] la que más cae: camisas 34.4 → 13.3 (b 2 · c 21 · p de Holm 0.00066) · rotas: ['camisas']
[slice] normal    n 600 · Δ -1.83 · Δmin -3.82 → pasa
[slice] poca_luz  n 210 · Δ -0.95 · Δmin -5.52 → NO PASA
[slice] chica     n 190 · Δ +0.00 · Δmin -4.13 → pasa
[calibración] ECE 0.0299 ≤ 0.05
✗ NO PASA: top-1 contra champion: Δmin -3.02 < −2.4 · categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066) · slice poca_luz: Δmin -5.52 < −5
[código 1]
Terminal
python mundo/modelos.py gates

Abre la corrida roja en MLflow (experimento c01-gate): el reporte está en sus artefactos.

Salida
FINISHED  17:40  cand-2026-10-01              vs v3 · pasa · —
FAILED    17:40  cand-2026-10-01-proveedor    vs v3 · no_pasa · top-1 contra champion: Δmin -3.02 < −2.4; categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066); slice poca_luz: Δmin -5.52 < −5
Terminal
python verificar.py frena
Salida
✓ frena            cand-2026-10-01-proveedor: FAILED · top-1 contra champion: Δmin -3.02 < −2.4; categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066); slice poca_luz: Δmin -5.52 < −5 · ninguna versión suya dice gate=passed

1/1 en verde
Listo cuando: El gate del proveedor quedó FAILED y su motivo nombra camisas (p de Holm 0.00066), además del top-1 global y el slice de poca luz.
Ojo: Un gate que atrapa la excepción «para que el pipeline no truene» deja la corrida en verde, salta los pasos siguientes y nadie se entera de que no hubo challenger.
Concepto de este paso
Fallar en rojofail loudlySi el gate no pasa, el paso termina con error (código de salida 1, corrida FAILED) y el pipeline se detiene y avisa. Nunca devuelve «false» y deja seguir.Analogía, por qué importa y la trampa

AnalogíaUna alarma de incendio que en vez de sonar escribe una nota en un cuaderno: técnicamente detectó el fuego.

Por qué importaUn gate que «devuelve false» deja que los pasos siguientes se salten en silencio: la corrida queda en verde, no aparece ningún challenger y nadie se entera.

TrampaAtrapar la excepción del gate «para que el pipeline no truene».

6Registrar el challengerEl candidato que pasó, como una versión nueva de classifier con sus tags y el alias challenger; champion no se toca.

Registrar no es «subir el modelo»: es dejar escrito qué es y por qué pasó. registrar.py busca la última corrida de gate del candidato y se niega si no terminó en verde, si sus reglas no estaban revisadas, si el examen no es el de gate.yaml o si champion ya no es la versión contra la que se comparó (un veredicto viejo). Después crea la versión apuntando a los archivos de la corrida, con sus tags (gate, snapshot, huellas de pesos y de labels.json, examen, champion y Δmin) y le pone challenger. Correrlo dos veces no crea dos versiones.

Pythonpipeline/registrar.py
"""Paso «registrar»: el candidato que pasó el gate se vuelve una versión de classifier con el alias challenger.

    python pipeline/registrar.py                          # el candidato de corrida.yaml
    python pipeline/registrar.py --candidato <corrida>

Contrato:
- Solo registra si hay una corrida de gate TERMINADA (FINISHED) para ese candidato, con veredicto «pasa», contra el
  champion de corrida.yaml, con un gate.yaml revisado y con el examen que dice gate.yaml. Si no, se detiene.
- Si champion ya no es la versión contra la que se evaluó, el veredicto es viejo: se detiene (hay que volver a evaluar).
- La versión apunta a los archivos de la corrida del candidato (runs:/<run_id>/modelo) y lleva sus tags: gate=passed,
  gate_run_id, mes, snapshot, pesos_sha256, labels_sha256 (el de entrada/categorias.json), examen, champion_version,
  y el Δmin contra el champion.
- Mueve challenger, nunca champion: champion lo mueve el despliegue cuando termina el canary (estación 10).
- Correrlo dos veces no crea dos versiones.
En C01 este paso va después de la estación 5 (paridad y latencia del engine). En el dojo no hay engine: registra aquí.
"""
from __future__ import annotations

import argparse
import json
import sys

from _comun import CLASES, EXP_GATE, MODELO, corrida, gate, mlflow_cliente, revisiones, sha256

ap = argparse.ArgumentParser()
ap.add_argument("--candidato")
a = ap.parse_args()
cfg, g = corrida(), gate()
candidato = a.candidato or cfg["candidato"]
c = mlflow_cliente()

exp = c.get_experiment_by_name(EXP_GATE)
rs = c.search_runs([exp.experiment_id], filter_string=f"tags.candidato = '{candidato}'", max_results=1,
                   order_by=["attributes.start_time DESC"]) if exp else []
if not rs:
    sys.exit(f"✗ {candidato} no tiene ninguna corrida de gate: corre evaluar.py y gate.py")
gr = rs[0]
t = gr.data.tags
if gr.info.status != "FINISHED" or t.get("veredicto") != "pasa":
    sys.exit(f"✗ el último gate de {candidato} no pasó ({gr.info.status} · {t.get('motivo', '?')}): no se registra")
if t.get("gate_yaml_sha256") not in {r["gate_yaml_sha256"] for r in revisiones()}:
    sys.exit("✗ ese gate se tomó con un gate.yaml que nadie revisó: no cuenta")
if t.get("examen") != g["examen"]["id"] or t.get("manifest_sha256") != g["examen"]["manifest_sha256"]:
    sys.exit("✗ ese gate usó otro examen que el de gate.yaml")
champion = c.get_model_version_by_alias(MODELO, "champion").version
if t.get("champion_version") != str(cfg["champion"]) or str(champion) != str(cfg["champion"]):
    sys.exit(f"✗ el gate comparó contra v{t.get('champion_version')}, y hoy champion es v{champion}: el veredicto es viejo. "
             "Vuelve a evaluar contra el champion de hoy")

run_id = t["candidato_run_id"]
cand = c.get_run(run_id)
ya = [mv for mv in c.search_model_versions(f"name = '{MODELO}'") if mv.run_id == run_id]
if ya:
    mv = ya[0]
    print(f"  {candidato} ya era {MODELO} v{mv.version}")
else:
    mv = c.create_model_version(MODELO, source=f"runs:/{run_id}/modelo", run_id=run_id, tags={
        "gate": "passed", "gate_run_id": gr.info.run_id, "mes": "2026-10", "snapshot": cand.data.tags["snapshot"],
        "pesos_sha256": cand.data.tags["pesos_sha256"], "labels_sha256": sha256((json.dumps(CLASES, ensure_ascii=False) + "\n").encode()),   # = el labels.json de la corrida
        "examen": t["examen"], "champion_version": t["champion_version"],
        "delta_min_champion_top1": str(gr.data.metrics["delta_min_champion_top1"])})
c.set_registered_model_alias(MODELO, "challenger", mv.version)
print(f"✓ {MODELO} v{mv.version} @challenger · gate {gr.info.run_id[:8]} · champion sigue en v{champion}")
Terminal
python pipeline/registrar.py --candidato cand-2026-10-01-proveedor
Salida
✗ el último gate de cand-2026-10-01-proveedor no pasó (FAILED · top-1 contra champion: Δmin -3.02 < −2.4; categoría camisas: recall 34.4 → 13.3 (−21.1 puntos, p de Holm 0.00066); slice poca_luz: Δmin -5.52 < −5): no se registra
[código 1]
Terminal
python pipeline/registrar.py
Salida
✓ classifier v4 @challenger · gate 06192ef5 · champion sigue en v3
Terminal
python pipeline/registrar.py

Otra vez: no duplica.

Salida
  cand-2026-10-01 ya era classifier v4
✓ classifier v4 @challenger · gate 06192ef5 · champion sigue en v3
Terminal
python mundo/modelos.py versiones
Salida
v1  —            mes 2026-07 · corrida equipo-2026-07-01 · gate passed · labels.json en orden
v2  —            mes 2026-08 · corrida equipo-2026-08-01 · gate passed · labels.json en orden
v3  @champion    mes 2026-09 · corrida equipo-2026-09-01 · gate passed · labels.json en orden
v4  @challenger  mes 2026-10 · corrida cand-2026-10-01 · gate passed · labels.json en orden
Terminal
python verificar.py registro
Salida
✓ registro         @champion = v3 · @challenger = v4 (cand-2026-10-01, gate 06192ef5 contra v3) · labels 97864728… · todo alias apunta a una versión con gate=passed

1/1 en verde
Terminal
python verificar.py
Salida
10/10 en verde
Listo cuando: classifier v4 @challenger con gate=passed y sus tags; @champion sigue en v3; los 10 checks en verde.
Ojo: Volver atrás (rollback) es mover el alias champion a la versión anterior: un comando, segundos. Por eso la versión vieja no se borra.
Concepto de este paso
Registro de modelosmodel registryEl catálogo de modelos: cada versión (v1, v2…) apunta a sus archivos y nunca cambia; los alias (champion, challenger) se mueven; los tags guardan de dónde salió.Analogía, por qué importa y la trampa

AnalogíaEl registro civil: cada acta tiene su número y no se reescribe; lo que cambia es quién ocupa qué puesto.

Por qué importaLa pregunta de la guardia a las 3 de la mañana, «¿qué modelo está sirviendo y de dónde salió?», se contesta con el alias y los tags, en un minuto.

TrampaCreer que los archivos de una corrida no cambian: en MLflow se pueden reemplazar. Por eso la versión guarda las huellas (pesos_sha256, labels_sha256).

Solo

10 objetivos

Empieza con python mundo/reiniciar.py --pipeline y haz commit del esqueleto.

Sin GUION.md: solo estos objetivos y el contrato arriba de cada archivo.

Cada objetivo tiene su check; corre python verificar.py <check> cuando creas que quedó.

Las reglas no se tocan: gate.yaml y corrida.yaml se quedan como vienen.

01El S3 local y MLflow arriba, el mundo creado y la carpeta en git.python verificar.py mundo
02Tu evaluación usa el examen congelado (manifest y fotos con su huella) y comprueba que no haya fuga.python verificar.py examenPista: ¿Dónde dice cuál es la huella correcta del examen?
03Los pares de los tres modelos, por número de versión, en el orden del manifest, con las predicciones de verdad.python verificar.py pares
04Todos los labels.json (versiones y candidato) son entrada/categorias.json.python verificar.py labels
05No inferioridad pareada en top-1 y top-5 contra champion y hace 3 meses: b, c y Δmin correctos.python verificar.py no-inferioridadPista: ¿Qué fotos cuentan para la diferencia?
06Por categoría: caída, McNemar exacto, Holm y «rota» correctos.python verificar.py categorias
07Δmin por slice y ECE del candidato.python verificar.py slices
08El gate del candidato del proveedor queda FAILED, con camisas en el motivo, y no se registra.python verificar.py frenaPista: ¿Qué código de salida ve el orquestador?
09Todos tus gates con un gate.yaml revisado, y sin cambios pendientes.python verificar.py umbrales
10El candidato bueno registrado como challenger, con sus tags; champion sigue en v3.python verificar.py registro

Romper

6 fallas

Con todo en verde, romper.py mete una falla en el mundo, la configuración o la infraestructura (nunca en lo que escribiste) y, si hace falta, deja corriendo lo que «pasó anoche». Tú empiezas por verificar.py.

Terminalromper.py
python romper.py --mostrar   # con ayuda: Claude sabe cuál es
python romper.py             # solo: escondida, ni Claude la sabe
python romper.py --verificar # ¿ya quedó?
python romper.py --revelar   # me rindo
python romper.py --restaurar # deshacer

Repaso

para el celular
El gate decide si vale la pena probar; el canary, si se queda.Reglas escritas antes (y cambiadas solo en un PR), el champion por número, el mismo examen congelado y los pares foto por foto. No inferioridad contra el champion y contra el de hace 3 meses, cada categoría y cada slice aparte, y si algo falla, en rojo. Promover y volver atrás es mover un alias. Trampa: Mover los umbrales después de ver el resultado («el slice cayó 6, subo el límite a 7»). El gate deja de medir y empieza a justificar. Listo cuando
  • El candidato es no inferior al champion y al de hace 3 meses (Δmin ≥ −margen, en top-1 y top-5), sobre el examen congelado y sin fuga.
  • Ninguna categoría cae más de 5 puntos con una caída significativa (McNemar + Holm), ningún slice cae más que su margen y el ECE está en su límite.
  • Las reglas eran las revisadas, y el champion entró por número.
  • Un candidato que rompe una categoría deja la corrida en rojo, con el motivo, y no se registra.
  • El candidato que pasó es una versión con gate=passed, sus huellas y el alias challenger; champion no se movió.
  • Sabes qué versión es champion y a cuál vuelves si algo falla.

Así te lo pueden preguntar en una entrevista

¿Cómo decides si el modelo reentrenado puede reemplazar al de producción?

Con un gate automático y reglas escritas antes: los dos modelos sobre el mismo golden set congelado, foto por foto. No inferioridad pareada (el extremo de abajo del intervalo de la diferencia ≥ −margen, con el margen del tamaño del ruido del examen), también contra el modelo de hace 3 meses por la erosión. Además, recall por categoría con McNemar y Holm, slices y calibración. Si pasa, se registra como challenger; el champion se mueve después del canary.

¿Por qué no inferioridad y no «que sea mejor»?

Porque el reentrenamiento mensual busca estar al día, no ganar. Exigir una mejora significativa bloquearía casi todos los meses, y «≥ champion» decide con el ruido: dos modelos iguales salen uno arriba del otro la mitad de las veces. La no inferioridad acepta perder menos de lo que el examen puede medir.

El top-1 global subió, pero una categoría grande se rompió. ¿Cómo lo atrapas?

Recall por categoría contra el champion con los pares de esa categoría: McNemar exacto con sus discrepancias, corregido con Holm porque son muchas pruebas, y además un tamaño mínimo de caída para que importe. Más slices: luz, tamaño, dispositivo.

¿Qué guarda la versión del registry?

Apunta a los artefactos (pesos, labels.json) y lleva tags: gate=passed y la corrida del gate, snapshot, commit, huellas de pesos y de labels.json, examen, contra qué champion se comparó y sus métricas. El alias challenger. Y nunca cambia: lo que se mueve son los alias.

Alguien quiere aflojar un umbral porque el modelo de esta semana no pasa. ¿Qué haces?

No lo muevo para este modelo. Si hay un argumento, va en un PR propio, revisado, que aplica desde la corrida siguiente, con la justificación (por ejemplo, el examen creció y el ruido bajó). Un override para una corrida concreta pide dos personas y deja un tag.

¿Cómo sabes que el examen no está contaminado?

El golden set se congela con un manifest y su huella, se excluye de todos los snapshots por diseño, y el gate cruza las huellas de las fotos del examen con las del snapshot del candidato antes de evaluar: una sola coincidencia detiene todo.

Versión del contenido: 17 de noviembre de 2026.

Contexto opcional

para consultar
Dónde estás en el pipeline

La estación 3 deja un checkpoint candidato con su corrida en MLflow. Esta decide si puede reemplazar al modelo que hoy atiende en producción (el champion), y no lo decide una persona viendo una gráfica: lo decide un gate, un paso automático del pipeline con reglas escritas antes de la corrida. El gate evalúa al candidato, al champion y al champion de hace 3 meses sobre el mismo examen congelado (el golden set), foto por foto. Pide que el candidato no sea peor por más de un margen (no inferioridad), que ninguna categoría se rompa, que ningún slice caiga y que su confianza diga la verdad. Si algo no se cumple, el pipeline se pone en rojo. Si todo pasa, el candidato queda en el registry como una versión nueva con el alias challenger. champion se mueve después, cuando termina el canary.

Entra
  • el checkpoint candidato: la corrida de MLflow que dejó la estación 3
  • el champion y el de hace 3 meses, por su número de versión (los resolvió el orquestador al arrancar)
  • el golden set congelado, con la huella de su manifest
  • las reglas del gate (gate.yaml), revisadas en un PR antes de la corrida
Sale
  • las predicciones de los tres modelos, foto por foto (los pares)
  • el reporte del gate: veredicto, motivo, no inferioridad, categorías, slices y calibración, en una corrida de MLflow
  • si pasa: una versión nueva de classifier con el alias challenger y sus tags; si no, una corrida roja que frena el pipeline
El escenario del proyecto
Con kit · 4 rondas

El kit trae el marketplace de C01 el 1 de octubre de 2026, a las 05:00 UTC: el entrenamiento del mes ya terminó y el pipeline llega al gate. En el S3 local están las fotos, los snapshots de junio a septiembre y el examen congelado golden-v1. En MLflow está el historial del registro (julio, agosto y septiembre, que hoy es champion) y dos candidatos de octubre: el bueno y uno entrenado con un lote de etiquetas malo del proveedor. Tú escribes el gate: evaluar a los tres modelos foto por foto, aplicar las reglas y registrar al challenger. Todo corre con un entorno virtual de Python y dos contenedores.

El mundo vive en dos servicios: el S3 local (fotos, snapshots y el examen) y MLflow (las corridas y el registro de modelos). mundo/crear.py los llena igual cada vez y entrena los cinco modelos del equipo, por eso tarda unos minutos. La carpeta tiene que ser un repositorio de git: el gate se niega a juzgar con reglas que no están en un commit.

Glosario: los 18 conceptos

Una línea para entenderlo; abre la tarjeta para la analogía, por qué importa y la trampa.

Gate de evaluaciónevaluation gateUn paso automático del pipeline que decide si un modelo puede avanzar, con reglas escritas antes. Si no se cumplen, el pipeline se detiene.Analogía, por qué importa y la trampa

AnalogíaEl examen de manejo: hay una lista de cosas que tienes que hacer bien, escrita antes de que te subas al coche, y el examinador no la cambia porque le caíste bien.

Por qué importaSin gate, el modelo nuevo llega a producción porque «se ve bien» en una gráfica. Con gate, cada mes se aplica la misma regla, y el historial dice por qué pasó o no pasó cada modelo.

TrampaUn gate que solo mira el promedio global: una categoría rota se esconde detrás de 9 que mejoraron un poco.

Golden set (examen congelado)golden set / frozen test setUn conjunto fijo de fotos con etiquetas revisadas, que ningún entrenamiento ve y que no cambia. Se identifica por su id y por la huella (sha256) de su manifest.Analogía, por qué importa y la trampa

AnalogíaEl metro patrón de París: si cada quien ajusta su metro, ya nadie mide lo mismo.

Por qué importaSolo con el mismo examen se pueden comparar modelos de meses distintos. Si se corrige algo, se publica golden-v2 en un PR propio y todos se vuelven a medir con él.

Trampa«Corregir» unas etiquetas del examen sin cambiarle el nombre: la comparación con los meses anteriores deja de valer y nadie lo nota.

Champion y challengerchampion / challengerChampion: el modelo que hoy atiende en producción. Challenger: el que pasó el gate y espera su turno (shadow y canary) para reemplazarlo.Analogía, por qué importa y la trampa

AnalogíaEl campeón de box y el retador: el retador tiene que ganarse la pelea; no basta con decir que está mejor entrenado.

Por qué importaLos dos son alias en el registry, nombres que apuntan a una versión. Cambiar de modelo, o volver atrás, es mover un alias, no reentrenar.

TrampaMover champion a mano «porque ya lo probé en el notebook»: el alias se mueve, pero nadie aprobó ese modelo.

Registro de modelosmodel registryEl catálogo de modelos: cada versión (v1, v2…) apunta a sus archivos y nunca cambia; los alias (champion, challenger) se mueven; los tags guardan de dónde salió.Analogía, por qué importa y la trampa

AnalogíaEl registro civil: cada acta tiene su número y no se reescribe; lo que cambia es quién ocupa qué puesto.

Por qué importaLa pregunta de la guardia a las 3 de la mañana, «¿qué modelo está sirviendo y de dónde salió?», se contesta con el alias y los tags, en un minuto.

TrampaCreer que los archivos de una corrida no cambian: en MLflow se pueden reemplazar. Por eso la versión guarda las huellas (pesos_sha256, labels_sha256).

Versión por númeropinned versionEl gate recibe el champion como número (v3), resuelto una sola vez al arrancar, nunca como la pregunta «¿quién es champion?».Analogía, por qué importa y la trampa

AnalogíaComparar contra «el récord de hoy» a media carrera es trampa: el récord puede cambiar mientras corres.

Por qué importaSi el alias se mueve a mitad de la corrida, las predicciones serían de un modelo y el veredicto contra otro. Con el número, el reporte dice exactamente contra quién se comparó.

TrampaRegistrar el veredicto de un gate que comparó contra un champion que ya no es champion: es un veredicto viejo.

No inferioridadnon-inferiority testPedir que el modelo nuevo no sea peor que el actual por más de un margen, con buena seguridad. No se le pide ganar.Analogía, por qué importa y la trampa

AnalogíaUn medicamento genérico más barato: no tiene que curar más que el original, solo no curar menos por más de un margen chico.

Por qué importaEl reentrenamiento mensual busca estar al día, no ganar. Exigir «mejor de forma significativa» bloquearía casi todos los meses; exigir «≥ champion» decidiría con una moneda.

TrampaMirar el centro (Δ) en vez del extremo de abajo (Δmin): un Δ de −0.5 puede pasar o no según cuánto ruido haya.

Margen de no inferioridadnon-inferiority marginCuánto se acepta que el modelo nuevo pierda contra el actual. Se fija antes, del tamaño del ruido del examen: lo que el examen ni siquiera puede medir.Analogía, por qué importa y la trampa

AnalogíaLa tolerancia de una báscula: si mide de ± 100 g, no tiene caso discutir por 50.

Por qué importaEn C01, 0.3 puntos (golden de 50,000). En el dojo, 2.4 (golden de 1,000). Es una decisión de negocio vestida de estadística: en C01, con ≈ 10 millones de fotos al día, 0.3 puntos son ≈ 30,000 primeras sugerencias equivocadas más al día.

TrampaElegirlo después de ver el resultado. Entonces ya no mide: justifica.

Evaluación pareadapaired evaluationLos dos modelos responden las mismas fotos y se comparan foto por foto: b = solo el nuevo acierta, c = solo el viejo acierta.Analogía, por qué importa y la trampa

AnalogíaDos cocineros preparan los mismos 1,000 platillos; para saber quién es mejor, solo importan los platillos en que uno acertó y el otro no.

Por qué importaLas fotos fáciles (los dos aciertan) y las imposibles (los dos fallan) no dicen nada; solo las discrepancias. Por eso la comparación pareada es más fina que comparar dos promedios.

TrampaGuardar solo «83.2 % vs 81.7 %»: sin los pares no hay prueba pareada, ni categorías, ni slices.

Error estándar e intervalostandard error / confidence intervalSE_Δ dice cuánto se movería la diferencia por azar con otras fotos. Δmin = Δ − 1.96 × SE es el extremo de abajo del intervalo de 95 %: lo peor que puede ser, con buena seguridad.Analogía, por qué importa y la trampa

AnalogíaEl margen de error de una encuesta: «42 % ± 3» quiere decir que lo real está, casi seguro, entre 39 y 45.

Por qué importaLa regla del gate es Δmin ≥ −margen. Con pocas discrepancias el intervalo es estrecho; con muchas, ancho.

TrampaConfundir el SE de un modelo solo (el del margen) con el SE pareado (el de la diferencia): el segundo es más chico.

Erosión de calidadslow regressionPerder un poco cada mes, siempre dentro del margen: cada comparación pasa, y la suma de un año es grande.Analogía, por qué importa y la trampa

AnalogíaLa rana en el agua que se calienta despacio: ningún grado de más se nota, la suma sí.

Por qué importaPor eso el gate compara también contra el champion de hace 3 meses: contra él se suman tres meses de pérdida, que no caben en el margen.

TrampaComparar solo contra el mes anterior y creer que eso protege del largo plazo.

Prueba de McNemarMcNemar's testPara dos modelos sobre las mismas fotos: si fueran igual de buenos, cada discrepancia sería un volado. La prueba da la probabilidad (p) de ver un reparto tan desigual de b y c por azar.Analogía, por qué importa y la trampa

AnalogíaSi una moneda sale 21 veces cruz y 2 águila, sospechas que está cargada: es muy raro por azar.

Por qué importaSepara una categoría rota (camisas: 2 contra 21) del ruido (playeras: 1 contra 4). Usa solo las discrepancias de esa categoría.

TrampaUsarla con muy pocas discrepancias y concluir «no hay diferencia»: con 3 discrepancias, ninguna prueba puede ver nada.

Corrección de HolmHolm–Bonferroni correctionAl hacer k pruebas a la vez, ordena las p de menor a mayor y compara la primera contra α/k, la segunda contra α/(k − 1)… Así la falsa alarma de todo el conjunto queda en α.Analogía, por qué importa y la trampa

AnalogíaSi compras 10 boletos de lotería, ganar uno ya no es tan sorprendente: hay que pedir más para creer que no fue suerte.

Por qué importaCon 10 categorías y α = 0.05 sin corregir, ≈ 40 % de los meses alguna «cae» por azar y el gate frena a un modelo sano.

TrampaNo corregir porque «cada prueba es al 5 %»: el 5 % es por prueba, no por gate.

Slicedata sliceUn pedazo del examen con algo en común: fotos con poca luz, fotos chicas, fotos del celular. Se evalúa aparte porque un promedio lo puede esconder.Analogía, por qué importa y la trampa

AnalogíaUn restaurante con 4.5 estrellas que da intoxicación los martes: el promedio no lo dice, el corte por día sí.

Por qué importaEl candidato del proveedor no se ve tan mal en global (−1.3 puntos) y en poca luz su Δmin cae a −5.5: ahí es donde más se nota el lote malo.

TrampaUsar el margen global en un slice chico: con 200 fotos el ruido es ≈ 5 puntos, y el gate se pondría en rojo por azar.

Calibración (ECE)calibration / expected calibration errorSi el modelo dice «90 % seguro», ¿acierta 9 de cada 10? El ECE agrupa las fotos por confianza y promedia la distancia entre confianza y aciertos.Analogía, por qué importa y la trampa

AnalogíaUn pronóstico del clima que dice «70 % de lluvia» y llueve 7 de cada 10 de esos días está bien calibrado.

Por qué importaProducto usa la confianza (por ejemplo, para pedir revisión humana debajo de un umbral). Un modelo que acierta igual pero dice «99 %» siempre rompe esa regla.

TrampaMirar solo la exactitud: dos modelos con el mismo top-1 pueden tener calibraciones muy distintas.

Fuga hacia el examendata leakage / test contaminationQue fotos del examen terminen en los datos de entrenamiento. El modelo ya vio las respuestas: sale mejor en el examen sin ser mejor.Analogía, por qué importa y la trampa

AnalogíaEstudiar con el examen que te van a poner: sacas 10 y no aprendiste nada.

Por qué importaEl gate cruza las huellas del snapshot del candidato con las del examen y se detiene si hay una sola en común. La estación 2 deja el golden set fuera por diseño.

TrampaCelebrar un candidato que «sube 3 puntos» sin preguntar con qué datos se entrenó.

labels.json: el orden es parte del modelolabel mapLa lista que dice qué categoría es cada salida de la red: la salida 0 es «playeras», la 1 «pantalones»… Viaja con los pesos y se registra con su huella.Analogía, por qué importa y la trampa

AnalogíaLas etiquetas de los frascos de la cocina: si las revuelves, el azúcar sigue siendo azúcar, pero le pones sal al café.

Por qué importaCon otro orden, los números del gate salen iguales (se evalúa por índice) y el gateway muestra otra categoría. Solo se nota si se compara el labels.json, o cuando cae la aceptación.

TrampaOrdenar las categorías alfabéticamente «para que se vea limpio».

Reglas escritas antespre-registered thresholdsLos umbrales del gate viven en un archivo versionado y cambian solo en un PR propio, revisado por otra persona, antes de la corrida.Analogía, por qué importa y la trampa

AnalogíaLas reglas del partido se acuerdan antes del silbatazo, no al medio tiempo cuando vas perdiendo.

Por qué importaSi se pueden mover después de ver el resultado, cada mes habrá un argumento razonable para aflojar, y el gate deja de medir.

Trampa«Solo por esta vez»: el commit directo a main que afloja una regla para que salga el modelo de la semana.

Fallar en rojofail loudlySi el gate no pasa, el paso termina con error (código de salida 1, corrida FAILED) y el pipeline se detiene y avisa. Nunca devuelve «false» y deja seguir.Analogía, por qué importa y la trampa

AnalogíaUna alarma de incendio que en vez de sonar escribe una nota en un cuaderno: técnicamente detectó el fuego.

Por qué importaUn gate que «devuelve false» deja que los pasos siguientes se salten en silencio: la corrida queda en verde, no aparece ningún challenger y nadie se entera.

TrampaAtrapar la excepción del gate «para que el pipeline no truene».

Nube real vs. local
En C01En el dojo
El examengolden-v3: 50,000 fotosgolden-v1: 1,000 fotos (las que la estación 3 dejó fuera de los snapshots), 600 normales, 210 con poca luz y 190 chicas
Categorías500; el gate revisa por separado las 100 con más tráfico10, todas
Margen de no inferioridad0.3 puntos2.4 puntos (el ruido de un examen de 1,000 fotos)
Contra quiénel champion (v14) y el de hace 3 meses (v12)el champion (v3, septiembre) y el de hace 3 meses (v1, julio)
Dónde correun paso del pipeline en una GPU (evaluar) y otro en CPU (el gate)la CPU de tu Mac: evaluar ≈ 10 s, el gate ≈ 3 s
Las reglasgate.yaml en el repositorio ml-catalogo; cambian solo en un PR revisadogate.yaml en tu carpeta; sus versiones revisadas, en mundo/revisiones.json
El registryMLflow con Postgres y S3MLflow en Docker, con SQLite y un volumen
En la nubeEn el dojoQué cambia
<code>golden-v3</code>: 50,000 fotos, 500 categorías<code>golden-v1</code>: 1,000 fotos, 10 categoríasLas mismas reglas con otra escala: el margen sale de la misma fórmula (2.4 puntos en lugar de 0.3) y cada categoría tiene ≈ 100 fotos.
El historial de PR del repositorio <code>ml-catalogo</code><code>mundo/revisiones.json</code>En C01, la rama protegida no deja subir gate.yaml sin revisión; aquí el gate comprueba la huella contra la lista de versiones aprobadas.
Los parámetros de la corrida de Argo<code>corrida.yaml</code>Los dos traen el champion ya resuelto a un número. El de verdad lo escribe el orquestador; el del dojo lo escribe mundo/crear.py.
Registrar después de la estación 5 (paridad y latencia del engine)<code>registrar.py</code> justo después del gateEn el dojo no hay engine: el challenger se registra en cuanto pasa el gate. En C01, primero se construye y se prueba el engine.
Evaluar en una GPULa CPU de tu Mac1,000 fotos de 32×32 caben en segundos; 50,000 de 224×224 con una ResNet-50, en minutos de GPU.
MLflow con Postgres y S3; Amazon S3MLflow con SQLite; RustFS en localhost:9500La misma API y la misma interfaz.
Qué trae el kit y qué escribes tú

Lo que trae no lo escribes

El S3 local y MLflow (compose.yaml). RustFS en el puerto 9500 (buckets fotos y ml-datos, este con versionado) y MLflow en el 5500, con su interfaz.

mundo/crear.py. Crea todo en ≈ 3 minutos: baja Fashion-MNIST, sube las 10,000 fotos, publica 4 snapshots, congela golden-v1 (1,000 fotos con su slice), entrena classifier v1, v2 y v3 (@champion) y los dos candidatos, y escribe corrida.yaml.

gate.yaml y mundo/revisiones.json. Las reglas del gate (el examen y su huella, contra quién, el margen, categorías, slices y calibración) y el registro de sus versiones revisadas: el sustituto del historial de PR.

corrida.yaml. Los parámetros de esta noche, ya resueltos: el candidato, champion = 3 y hace_3_meses = 1.

mundo/gateway/ y mundo/arquitectura.py. El preprocess del gateway (el mismo de la estación 3) y la red.

mundo/modelos.py y mundo/s3.py. Mirar y reparar el registro (versiones, alias, candidatos, gates, labels) y el S3 (el examen, sus versiones y restaurar una).

verificar.py y romper.py. 10 checks con los criterios de «listo» y 6 fallas en el mundo, la configuración o la infraestructura, nunca en lo que escribes.

Lo que escribes lo escribes tú

  1. pipeline/evaluar.pyLos tres modelos por número, con sus huellas, sobre el examen congelado (sin fuga): los pares, foto por foto.
  2. pipeline/gate.pyLas reglas revisadas: no inferioridad pareada, categorías con McNemar y Holm, slices y ECE. Si no pasa, en rojo.
  3. pipeline/registrar.pySolo con un gate que pasó: la versión nueva con sus tags y el alias challenger.
Reglas CLAUDE.md del kit
El CLAUDE.md del kitLas reglas de fondo para Claude Code en la carpeta del kit. Ya viene en el .zip.
Ver el CLAUDE.md
prompt
# Dojo de entrenamiento ML engineer's · C01 · Estación 4: Gate de evaluación y registry

Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin GPU ni nube, la estación «Gate de evaluación y registry» del caso C01: decidir, con reglas escritas antes y números foto por foto, si el modelo nuevo puede reemplazar al de producción, y dejarlo registrado como challenger con todo lo que dice qué es. La persona con la que trabajas está aprendiendo; tu trabajo es que **entienda**, no que termine rápido.

## Qué es cada cosa

| Carpeta o archivo | Qué es | ¿Se toca? |
|---|---|---|
| `mundo/` | La empresa ficticia: `crear.py` (fotos, snapshots, el examen congelado, el historial del registro y los dos candidatos de octubre), `arquitectura.py` (la red), `gateway/` (el preprocess del gateway), `modelos.py` (mirar y reparar el registro de MLflow), `s3.py` (mirar el S3 y sus versiones), `revisiones.json` (las versiones aprobadas de `gate.yaml`), `equipo.py`, `reiniciar.py` y el esqueleto. | **No.** Es el mundo. `modelos.py` y `s3.py` sí se usan. |
| `pipeline/evaluar.py`, `gate.py`, `registrar.py` | Lo que escribe la persona. Cada archivo trae su contrato arriba. | **Sí.** |
| `pipeline/_comun.py` | Lo que comparten los pasos: `corrida()`, `gate()`, `revisiones()`, `s3()`, `mlflow_cliente()`, `git()`, `sha256()`, `huella_pesos()` y las constantes. | No. |
| `gate.yaml` | Las reglas del gate (del equipo, revisadas en un PR). | Solo con una revisión aprobada. Nunca para que un modelo pase. |
| `corrida.yaml` | Los parámetros de esta noche, ya resueltos por el orquestador: candidato, champion y el de hace 3 meses, por número. | No a mano. |
| `entrada/categorias.json` | Las 10 categorías; su orden es el `label_id` y es el `labels.json` correcto. | No. |
| `reportes/` | Lo que dejan `evaluar.py` y `gate.py` de cada candidato: pares, evaluación y reporte. Git la ignora. | No a mano. |
| `data/` | Caché local: Fashion-MNIST. Git la ignora. | No. |
| `verificar.py` | Revisa los criterios de «listo», uno por check. | No. |
| `romper.py` | Mete fallas en el mundo, la configuración o la infraestructura. Nunca en lo que escribe la persona. | No. Y no leas su código para adivinar una falla escondida. Tampoco leas `mundo/equipo.py` para resolver un paso. |
| `GUION.md` / `OBJETIVOS.md` | El paso a paso (Construir con ayuda) y solo los objetivos (Construir solo). | No. |
| `taller/progreso.json`, `BITACORA.md` | El registro de las rondas. | Sí, tú los mantienes (ver abajo). |
| `taller/registro.py` | Lo usan `verificar.py` y `romper.py` para anotar en `progreso.json` sus corridas y las fallas cerradas. | No. |

## Cómo se trabaja

- Responde en español neutro, de tú, directo y sin relleno. Términos técnicos en inglés la primera vez, con su explicación.
- Explica siempre el **por qué**. Cuando algo en el dojo es distinto de C01 real (1,000 fotos de examen en lugar de 50,000, 10 categorías en lugar de 500, un margen de 2.4 puntos en lugar de 0.3, `mundo/revisiones.json` en lugar del historial de PR, `corrida.yaml` en lugar de los parámetros de Argo, registrar aquí en lugar de después de la estación 5), dilo en una línea.
- Nunca inventes salidas: si no corriste algo, di que no lo corriste.
- El entorno virtual va activo en cada comando: `source .venv/bin/activate`.
- Antes de correr algo que cambia el mundo o la máquina (`pipeline/gate.py`, `pipeline/registrar.py`, `mundo/modelos.py alias|quitar|labels`, `mundo/s3.py restaurar`, `pip install`, `docker compose …`, `romper.py`, `mundo/*.py`, `git commit`, `git revert`), dilo. Lo que solo lee (`verificar.py`, `pipeline/evaluar.py`, `mundo/modelos.py versiones|candidatos|gates`, `mundo/s3.py ls|golden|tarjeta|versiones`, `git status`, `git log`, `git diff`) se puede correr directo.
- `evaluar.py` tarda ≈ 10 s y el gate ≈ 3 s. `mundo/crear.py`, ≈ 4 min.
- Las reglas no se mueven para que algo pase. Si la persona propone cambiar un umbral después de ver un resultado, explícale por qué no, y cómo se haría bien (un PR propio, antes de la corrida siguiente).
- La interfaz de MLflow está en http://localhost:5500. Úsala para enseñar: las corridas de gate (las rojas también), sus tags, el reporte, las versiones y sus alias.
- Sigue el prompt de la ronda que te pegaron: en Construir solo y en Romper solo **no das código ni pistas** salvo que la persona se rinda.

## Bitácora

Al terminar cada paso, objetivo o falla, agrega una entrada en los dos archivos:

`BITACORA.md`, legible en el celular:

```markdown
## 2026-11-18 10:42 · Construir con ayuda · paso 3 (no inferioridad)
- **Hice:** …
- **Medí:** … (números reales que salieron)
- **Sigue:** …
```

`taller/progreso.json`, el que se importa en «Tu tablero» del Dojo (la página /tablero/ de la app). Agrega a `bitacora` y actualiza `rondas`:

```json
{
  "estacion": "c01-gate",
  "rondas": {
    "guiado":       { "estado": "en_curso", "inicio": "2026-11-18T10:05:12-06:00", "fin": null },
    "solo":         { "estado": "pendiente", "inicio": null, "fin": null, "pistas": 0 },
    "romper_ayuda": { "estado": "pendiente", "fallas": [] },
    "romper_solo":  { "estado": "pendiente", "fallas": [] }
  },
  "bitacora": [
    { "fecha": "2026-11-18T10:42:30-06:00", "ronda": "guiado", "paso": "no-inferioridad", "hice": "…", "medi": "…", "sigue": "…" }
  ],
  "verificaciones": [
    { "fecha": "2026-11-18T10:41:02-06:00", "pasan": ["mundo", "examen"], "fallan": [] }
  ]
}
```

- `estado` es `pendiente`, `en_curso` o `hecha`. En el tablero, `guiado` se llama «Construir con ayuda», `solo` «Construir solo», `romper_ayuda` «Romper con ayuda» y `romper_solo` «Romper solo».
- **Fecha y hora en cada avance**, en ISO 8601 con la zona de la Mac: sácala con `date -Iseconds` (da algo como `2026-11-18T10:42:30-06:00`). Nunca solo la fecha.
- `verificaciones` la escribe `verificar.py` solo, en cada corrida. No la edites.
- Cada falla la anota `romper.py` al cerrarla (`--verificar` o `--revelar`): `{ "id", "inicio", "fin", "minutos", "pistas": 0, "rendido", "aprendi": "" }`, con el tiempo real. Tú solo completas `pistas` y `aprendi` en esa misma entrada (la última de su ronda); no agregues otra.
- Mantén el JSON válido: después de editarlo, corre `python -m json.tool taller/progreso.json > /dev/null`.

La estación completa, con su lugar en el mapa: cheat sheet «Del dato a producción».

La teoría, en Sensei

Sensei es el curso de teoría desde cero de TrueML. Su lección de esta estación explica el porqué de lo que aquí construyes; léela antes o vuelve a ella cuando algo no cierre.

Lección de la estación 4Gate de evaluación y registryLeer en Sensei ↗ Si te falta base, lee antes