Crear y comprobar cards

Una card es una sesión de construcción acotada. Este es el ciclo en el que pasarás la mayor parte del tiempo una vez que la planificación está completa.

Prerrequisito

/flow card se niega hasta que los seis gates de planificación han pasado o llevan una línea de deuda abierta que corresponda. Si se niega, ejecuta /flow y arregla el stage que nombre.

Corta la card

/flow card

Esto crea la siguiente cards/C-NNN.md. Antes de escribir una línea de código, léela y rellena lo que pide la plantilla:

Sección	Para qué es
## Allowed files	Las únicas rutas que esta sesión puede tocar. Este es el radio de explosión.
implements:	Los ids de requisito del PRD (FRn) que reclama esta card.
## Verify	Comandos que realmente ejecutarás, no aspiraciones.
## Independent test	La prueba del trozo visible para el usuario — o infra / none si genuinamente no es ninguno.
## Evidence	Se deja vacía hasta terminar. Aquí va la prueba real del mundo.
risk / risk-reason	La clase de riesgo, necesaria antes de cualquier ejecución autónoma.

Un [FILL] sin rellenar en ## Independent test suspende check, así que no lo saltes.

Carga primero el conocimiento previo

/flow recall

Deuda abierta, la última retro, el alcance de la card anterior, fricción del harness y playbooks promovidos. Trata la salida como contexto que aplicar, no como ruido.

Opcionalmente márcala en vuelo

/flow card start C-001

Esto registra la card como en curso en un registro portable cards/.inflight para que aparezca en /flow status. Nunca toca el campo con gates status:, y es totalmente opcional — editar a mano sigue funcionando.

Construye dentro de las líneas

Tres reglas atan cada sesión de construcción:

1. Una card por sesión. Ni dos, ni dos en paralelo hasta que /flow ready diga que son seguras.
2. Toca solo ## Allowed files. Salirte de esa lista es exactamente lo que busca el revisor.
3. El contrato es la costura. Construye hacia las formas que declaró el stage 05. Si una forma está mal, enmienda primero el contrato, luego el código.

Para una card de UI, la card de mock debe aprobarse antes de cualquier código de frontend, y /flow design <file> ejecuta la comprobación mecánica de DESIGN.md sobre ella.

Comprueba qué cards son seguras en paralelo

/flow ready

Lista las cards todo construibles con una pista de seguridad en paralelo basada en archivos permitidos solapados.

Comprueba la card

/flow check C-001

La capa mecánica valida primero la card: validez del estado, marcadores [FILL] restantes, secciones requeridas, y si ## Evidence está realmente poblada. Solo después de que pasa empieza la revisión semántica — diff versus alcance, deriva de archivos permitidos, conformidad de formas del contrato, DESIGN.md para UI, y si la evidencia es genuinamente estado del mundo.

El fallo que encontrarás más a menudo:

  [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)
FAIL: C-001 has gate violations (above).

Esto se dispara incluso cuando la construcción está terminada y todos los tests están en verde. «Tests pass» y «fusionado» son estados intermedios.

Pega evidencia que cuenta

Qué cuenta depende del tipo de proyecto:

Tipo de proyecto	Evidencia que pasa
web	La URL desplegada en vivo más salida real de curl
cli	Una invocación real con su salida real y código de salida
library	La API pública importada, un ejemplo de uso que funciona, umbral de cobertura cumplido
skill	Instalado en el home del skill, más una ejecución real que alcanza su definición de terminado

Los artefactos de proceso — un PR aprobado, una insignia de CI en verde, notas de release — no son evidencia. El suelo mecánico rechaza la prosa solo-de-proceso, así que una card no puede marcarse como terminada con papeleo.

Para la regla completa de qué cuenta, ver Terminado significa estado del mundo.

Pásala a terminada

/flow check C-001
PASS: C-001 is valid (status: done).

O deja que el CLI sea dueño del cambio:

/flow card done C-001

card done aplica las mismas reglas de terminado que check y revierte el cambio si el gate falla, así que nunca puede producir un terminado hueco. Editar a mano status: done y ejecutar check sigue siendo igualmente válido.

Converge el plan de vuelta al código

Las construcciones reales derivan: se escribe código que el plan nunca pidió, y trabajo planificado nunca aterriza en silencio. /flow converge es el cierre de esa brecha. No es un gate de next. Opt-in.

Evalúa el código presente contra el plan (FRn del PRD, interfaces del contrato, INV-n de la constitución). Escribe un payload flow-converge/v1 describiendo las brechas, luego ejecuta:

/flow converge

O flow.sh converge --file <path>.

Tres reglas atan el verbo:

1. Solo añadir. Nunca edites, renumeres ni elimines un cards/C-*.md existente. Nunca toques código de aplicación. Se emiten cards de resto; una sesión posterior las construye.
2. Todo o nada. El runner es transaccional: se escriben todas las cards de resto, o ninguna. Sin añadidos parciales.
3. CONVERGED significa no escribir nada. Cero hallazgos (o sin payload) imprime CONVERGED y deja cards/ intacto.

El trabajo que existe en el código pero nunca se pidió se convierte en una card de revisión (implements: none), nunca en una eliminación. Decidir eliminar algo es decisión del operador.

Tipos de brecha que acepta el payload: missing, partial, contradicts, unrequested. Cualquier otro se rechaza y no se escribe nada.

Escribe los hallazgos primero en .flow/converge-pending.md (estado de ejecución, gitignored, para que una ejecución CONVERGED nunca ensucie cards/). Presenta la tabla de hallazgos antes de escribir cualquier card. Formato:

schema: flow-converge/v1
findings: 2

---
gap-type: missing
severity: HIGH
implements: FR2
source-ref: 03-prd.md:FR2
title: implement the mark-task-done endpoint
deps: C-002
allowed: src/app.py
---
gap-type: unrequested
severity: LOW
implements: none
source-ref: src/app.py:debug_dump
title: the debug_dump surface no feature asked for
deps:
allowed: src/app.py

Las cards añadidas traen [FILL] en Verify y Evidence — aún no están construidas. Córtalas, rellénalas y hazles check como a cualquier otra card.

La taxonomía de brechas y el esquema completo del payload quedan en skills/flow/references/converge.md.

Ver también

• Terminado significa evidencia del mundo
• Saltar un gate con deuda
• Ejecutar una construcción auto