Verificabilidad: criterios de aceptación, fichas de feature y cobertura verificada en CI

[polmarza]

¿Qué se hizo?

Se cierra el hueco entre "el agente dice que está hecho" y "está hecho": los requisitos del PRD pasan a llevar criterio de aceptación comprobable, aparece una capa nueva (docs/features/) donde cada unidad de trabajo declara cómo se validará, el PR se cierra con evidencia pegada en vez de casillas, y un script verifica todo eso en CI.

Añade además tres cosas que faltaban y no dependen del stack: una tabla de proporcionalidad (qué documentos exige cada tamaño de proyecto), una sección de límites de ejecución, y los comandos /feature y /doctor.

Motivación

El protocolo era enteramente autodeclarado. Todas las reglas eran "el agente debe", y el checklist del PR lo marcaba el mismo agente que había hecho el trabajo: quien afirmaba haber verificado y quien tenía que verificar eran el mismo. Una casilla marcada no distingue entre "lo ejecuté y pasó" y "estoy razonablemente seguro de que pasaría".

El hueco de fondo era otro: la plantilla gobernaba el proyecto pero no la unidad de trabajo. Una feature existía como conversación → código → entrada de changelog escrita a posteriori, sin ningún artefacto que fijara el acuerdo antes del código. El alcance se renegociaba solo, sin que nadie lo notara.

Requisitos que cierra

Ninguno. Este repositorio es el andamiaje: no tiene PRD con requisitos propios.

Tipo de cambio

• Feature
• Fix
• Refactor
• Migración
• Documentación
• Configuración

Evidencia

1. El script sobre este repositorio (plantilla sin rellenar, sin fichas):

$ node scripts/verificar-cobertura.mjs
Sin fichas de feature todavía: nada que verificar.
$ echo $?
0

Era el caso crítico: si un clon recién hecho diera rojo, el workflow nacería desactivado.

2. Ficha Verificada, con test existente y una excepción bien justificada (sobre una copia del repo, con fixtures):

Verificación de cobertura — 1 ficha(s)

  ATENCIÓN  M-03 no aparece en ninguna ficha todavía  (docs/prd.md)

Sin fallos. 1 aviso(s) que no bloquean.
→ salida: 0

3. Ficha En construcción con el test todavía sin escribir — no debe fallar, porque los tests se escriben después de implementar:

Verificación de cobertura — 1 ficha(s)

  ATENCIÓN  M-01 no aparece en ninguna ficha todavía  (docs/prd.md)
  ATENCIÓN  M-02 no aparece en ninguna ficha todavía  (docs/prd.md)

Sin fallos. 2 aviso(s) que no bloquean.
→ salida: 0

4. Los nueve modos de fallo mezclados:

Verificación de cobertura — 3 ficha(s)

  docs/features/en-construccion.md
    FALLO  M-03: la ficha está Verificada pero tests/exportar.spec.ts no existe

  docs/features/rota.md
    FALLO  Estado "A medias" no válido. Debe ser: Acordada · En construcción · Verificada
    FALLO  M-01: la columna "Se valida con" está vacía. Escribe la ruta del test o "no verificable por interfaz: <razón concreta>"
    FALLO  M-02: la excepción no explica nada ("no aplica"). Escribe la razón concreta y cómo se comprueba entonces
    FALLO  M-04: no está declarado en docs/prd.md
    FALLO  M-05: no está declarado en docs/prd.md
    FALLO  M-05: "pendiente" no es ni una ruta de test ni una excepción justificada
    FALLO  M-09 aparece en "Requisitos que cierra" pero no tiene fila en la tabla

  docs/features/sin-tabla.md
    FALLO  No tiene sección `## Cobertura`

9 fallo(s).
→ salida: 1

Verificación de los requisitos:

No aplica: este PR no cierra ningún requisito de PRD (ver sección anterior). Lo que se verifica es el comportamiento del propio script, y está arriba: los cuatro escenarios, con los códigos de salida.

Checklist

• Los documentos afectados en docs/ están actualizados — prd.md, testing.md, architecture.md y el nuevo features/README.md
• La ficha de docs/features/ está en estado Verificada — no aplica: este repositorio es el andamiaje y no tiene fichas propias. docs/features/ llega vacía a los proyectos que usen la plantilla
• Hay una entrada en changelog/ con este cambio — dos entradas, en .template/changelog/, que es donde el protocolo manda registrar los cambios sobre el andamiaje para que quien use la plantilla arranque con el changelog limpio
• La sección "Evidencia" contiene salida real de comandos, no una descripción de lo que pasaría
• Se ha ejecutado /security-review si hay cambios sensibles — no se ha ejecutado. Revisión manual del único cambio con superficie real, el workflow: usa pull_request y no pull_request_target, con lo que los PR desde forks corren con token de solo lectura y sin acceso a secretos; no consume ningún secreto, no instala dependencias y el script solo lee archivos del repositorio. Si prefieres pasarlo igualmente antes de mergear, dilo y lo lanzo

---

Nota sobre el historial: va en un solo commit a propósito. Los dos bloques —la metodología y la verificación ejecutable— comparten los mismos archivos (CLAUDE.md, README.md, /doctor, docs/features/README.md), y separarlos habría dejado un commit intermedio con documentación apuntando a un script que todavía no existe. La separación sí está en las dos entradas de .template/changelog/.