Máquina de estados y puerta de aprobación

El semáforo y el examen

Un semáforo no pregunta a los coches si creen que pueden pasar. Cambia de color según reglas fijas. Un examen tampoco: no apruebas porque te sientas preparado, sino porque sacas la nota.

Con las funciones del proyecto queremos lo mismo: que su estado no sea una opinión del agente sino el resultado de una regla.

Los cuatro estados

La lección define cuatro estados para cada función:

La plantilla feature_list.json del curso usa in_progress en lugar de active y el mismo resto. El nombre da igual; lo que importa es que sean pocos, claros y estén documentados en una leyenda dentro del propio archivo.

not_started ──> active ──(verificación OK)──> passing
                  │  ▲
     (falla)──────┘  │
                  └──> blocked ──(se resuelve)──> active

La puerta de aprobación (pass-gate)

La regla clave: solo se pasa de active a passing si la verificación se ejecuta con éxito. A esto se le llama pass-state gating, algo como «puerta de estado de aprobación». Además, en la idea de la lección, una vez aprobada no se vuelve atrás por capricho: es como una nota de examen, no se cambia a posteriori.

La política de aprobación que acompaña a la lección fija cuatro condiciones para que una función pase de passes: false a passes: true:

• el flujo esperado se ha ejecutado de verdad;
• la evidencia del éxito está registrada;
• no hay errores bloqueantes en la ruta probada;
• la implementación no deja la aplicación rota o ambigua.

Quién cambia el estado

El agente no debería editar libremente el campo de estado. Su papel es pedir la verificación; el harness (por ejemplo un script) ejecuta el comando y, si pasa, actualiza el estado y guarda la evidencia. Es la diferencia entre una restricción de base de datos, que ningún SQL puede saltarse, y una convención que depende de que nadie se despiste.

En la práctica, puedes empezar de forma sencilla: una regla en AGENTS.md que prohíba tocar el estado sin ejecutar antes la comprobación y exija anotar la evidencia. Si más adelante automatizas el script, mejor.

La presión que ejerce la lista

El número de funciones que aún no están en passing es la presión del harness sobre el agente. Presión cero significa proyecto completo. Mientras haya funciones pendientes, la lista le dice al agente qué toca después, sin que nadie se lo recuerde.

Un ejemplo de transición

{
  "id": "chat-003",
  "status": "passing",
  "evidence": [
    "Verificación ejecutada: crear 2 conversaciones, reiniciar, ambas visibles",
    "Commit abc1234"
  ]
}

Fíjate en que el estado y la evidencia van juntos. Un passing sin evidencia es un candidato a mentira.