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

.claude/commands/changelog.md

@@ -3,6 +3,8 @@ Crea una nueva entrada en `changelog/` siguiendo el protocolo del proyecto.
 1. Usa la fecha y hora actuales para nombrar el archivo: `YYYY-MM-DD_HH-MM_descripcion-breve.md`
 2. Si el usuario no ha indicado qué cambio registrar, pregúntale.
 3. Rellena las tres secciones obligatorias: qué se hizo, qué archivos se modificaron, por qué.
-4. Si el cambio afecta algún documento de `docs/`, recuérdale al usuario que hay que actualizarlo en esta misma sesión.
+4. Rellena el campo `Requisitos` con los IDs del PRD que este cambio deja terminados (`M-01`, `S-02`…). Si es un cambio interno —refactor, tooling, documentación— escribe "ninguno"; no lo dejes en blanco.
+5. Si el cambio cierra una feature, comprueba que su ficha de `docs/features/` está en estado **Verificada** antes de escribir la entrada.
+6. Si el cambio afecta algún documento de `docs/`, recuérdale al usuario que hay que actualizarlo en esta misma sesión.
 
 Si existe la carpeta `.template/` y el cambio es sobre la plantilla en sí (CLAUDE.md, docs vacíos, comandos, plantillas de GitHub), escribe la entrada en `.template/changelog/` en lugar de `changelog/`. La carpeta `changelog/` se reserva para el proyecto que use la plantilla.

.claude/commands/doctor.md

@@ -0,0 +1,72 @@
+Revisa el estado del proyecto y del entorno, y da un parte de qué está bien, qué falta y cómo
+arreglarlo. **Solo diagnostica: no arregla nada por su cuenta.** Al terminar, propón las
+correcciones y deja que el usuario decida cuáles aplicar.
+
+Ejecútalo cuando alguien entra al proyecto por primera vez, cuando algo falla sin motivo aparente
+o antes de una sesión larga, para no descubrir a mitad que faltaba media configuración.
+
+## Qué comprobar
+
+### 1. Documentación
+
+- ¿Existen todos los archivos que `CLAUDE.md` marca como obligatorios para este proyecto? (La
+  obligatoriedad depende del tamaño: mira la tabla "Qué documentación necesita cada proyecto".)
+- ¿Alguno está vacío — solo comentarios `<!-- -->`, sin contenido real?
+- ¿Sigue existiendo `.template/`? Entonces la inicialización quedó a medias.
+
+### 2. Fichas de feature
+
+Ejecuta la verificación de cobertura y reporta su salida tal cual:
+
+```bash
+node scripts/verificar-cobertura.mjs
+```
+
+Comprueba las tablas contra `docs/prd.md`: filas sin validación declarada, excepciones que no
+explican nada, identificadores inexistentes y tests prometidos que no existen en fichas
+**Verificada**. Sus FALLO son FALLO aquí; sus ATENCIÓN son ATENCIÓN.
+
+Añade a mano lo que el script no mira, porque requiere criterio:
+
+- Fichas en **En construcción**: son trabajo a medias. Di cuáles y desde cuándo.
+- Tests declarados que existen pero están vacíos o sin aserciones reales. El script solo comprueba
+  que el archivo esté ahí; si te cruzas con uno hueco, es un FALLO aunque la verificación pase.
+
+### 3. Entorno
+
+- Versión de Node y de pnpm frente a lo que declare `CLAUDE.md`. Si no coinciden, dilo: la mayoría
+  de fallos raros de instalación son esto.
+- ¿Están las dependencias instaladas (`node_modules/`)? ¿El lockfile está al día respecto a
+  `package.json`?
+- Variables: compara los nombres de `.env.example` con los que hay definidos en el entorno o en
+  `.env.local`. Reporta **solo los nombres que faltan**. Nunca imprimas un valor, ni completo ni
+  parcial, ni siquiera para confirmar que es correcto.
+
+### 4. Servidores MCP
+
+Ejecuta `claude mcp list`. Contrasta el resultado con la tabla "MCPs del proyecto" de
+`docs/architecture.md`:
+
+- Servidores documentados que no arrancan o no aparecen.
+- Servidores configurados que no están documentados.
+
+### 5. Tests
+
+- ¿Existe el comando de test que declara `docs/testing.md`? ¿Arranca?
+- Si es barato, ejecútalo y reporta el resultado real. Si tarda o necesita servicios levantados, no
+  lo lances: di que no se ha ejecutado y por qué. **No des por bueno lo que no has visto pasar.**
+
+## Cómo reportar
+
+Una tabla, un renglón por comprobación:
+
+| Comprobación | Estado | Detalle |
+|--------------|--------|---------|
+| Documentación | OK | 6 de 6 archivos con contenido |
+| Fichas de feature | ATENCIÓN | `registro-usuarios` lleva 3 semanas En construcción |
+| Node / pnpm | FALLO | pnpm 10.4 instalado, el proyecto pide v11 |
+
+Tres estados y nada más: **OK**, **ATENCIÓN** (funciona pero hay deuda) y **FALLO** (algo está roto
+o falta). Para cada FALLO, di el comando exacto que lo arregla.
+
+Si todo está en orden, dilo en una línea y no adornes el informe.

.claude/commands/feature.md

@@ -0,0 +1,45 @@
+Crea la ficha de una feature nueva en `docs/features/`, siguiendo el formato de
+`docs/features/README.md`.
+
+Esto se hace **antes** de escribir código, no después. La ficha es el acuerdo previo; si ya hay
+código escrito, lo que toca es una entrada de changelog, no una ficha retroactiva.
+
+## 1. Comprueba que hace falta
+
+Una ficha se justifica si el trabajo cierra requisitos del PRD, toca varias capas o va a durar más
+de una sesión. Para un arreglo puntual o un cambio de copy, dilo y no la crees: basta el changelog
+al terminar.
+
+## 2. Reúne el contexto
+
+Lee `docs/prd.md` para localizar qué requisitos (`M-01`, `S-02`…) cierra esta feature. Si el
+trabajo no se corresponde con ningún requisito del PRD, hay dos posibilidades y conviene
+preguntarlas antes de seguir:
+
+- Es alcance nuevo → hay que añadirlo al PRD primero, con su ID y su criterio de aceptación.
+- Está fuera de alcance → va a `mejoras/`, no a `docs/features/`.
+
+Lee también `docs/architecture.md` y `docs/data-model.md` si la feature toca estructura o datos.
+
+## 3. Pregunta lo que no puedas deducir
+
+- Nombre de la feature (el archivo será `kebab-case.md`)
+- Qué debe poder hacer el usuario cuando esto exista
+- Qué queda explícitamente fuera
+
+## 4. Escribe la ficha
+
+Usa la plantilla de `docs/features/README.md`. Estado inicial: **Acordada**.
+
+La tabla de cobertura se rellena entera, sin huecos. Por cada requisito, la tercera columna lleva
+o la ruta del test que lo validará, o `no verificable por interfaz: <razón concreta>` seguido de
+cómo se comprobará entonces. Si no sabes cuál de las dos poner, pregunta — no lo dejes en blanco
+ni escribas un test que sabes que no vas a escribir.
+
+## 5. Confirma antes de construir
+
+Enseña la ficha al usuario y pregunta si el acuerdo es correcto. Con su visto bueno, cambia el
+estado a **En construcción** y empieza.
+
+Mantén el estado al día durante el trabajo, no al final: es lo que permite retomar la feature en
+otra sesión sin reconstruir el contexto.

.claude/commands/init-proyecto.md

@@ -5,7 +5,9 @@ Convierte esta plantilla en el repositorio del proyecto real. Es un proceso de u
 1. Lee todos los archivos de `docs/`.
 2. Si están vacíos o incompletos, **no inicialices todavía**: primero complétalos con el usuario
    siguiendo el orden de `CLAUDE.md` (prd.md → business.md → design-system.md → architecture.md →
-   data-model.md → roadmap.md → user-flows.md).
+   data-model.md → roadmap.md → user-flows.md). No hacen falta los ocho: mira antes la tabla "Qué
+   documentación necesita cada proyecto" de `CLAUDE.md` y pide solo los que apliquen al tamaño de
+   este proyecto.
 3. Si no existe `.template/`, el repo ya está inicializado. Dilo y no toques nada, salvo que el
    usuario pida rehacer algo concreto.
 
@@ -32,12 +34,18 @@ Ejecuta el checklist de "Inicialización del proyecto" de `CLAUDE.md`:
 4. `.env.example` — deja solo las variables del stack real.
 5. MCPs — pregunta qué servidores MCP quiere y con qué alcance, siguiendo el "Protocolo de MCPs"
    de `CLAUDE.md`. Si prefieres tratarlo aparte, lanza `/mcp-setup`.
-6. `mejoras/backlog.md` — borra el ejemplo comentado.
-7. `.template/` — bórrala (`rm -rf .template`).
-8. `changelog/` — crea la primera entrada real del proyecto (tipo: Configuración) con `/changelog`
+6. `docs/` — borra los documentos que este proyecto no necesite según la tabla de tamaños. Los que
+   no aplican se borran, no se dejan vacíos: un archivo con solo comentarios hace que el arranque
+   de cada sesión se pare a preguntar por él. `docs/features/` se queda vacía, solo con su
+   `README.md`.
+7. `mejoras/backlog.md` — borra el ejemplo comentado.
+8. `.template/` — bórrala (`rm -rf .template`).
+9. `changelog/` — crea la primera entrada real del proyecto (tipo: Configuración) con `/changelog`
    y limpia de `changelog/README.md` la referencia a la plantilla.
-9. Verifica que no queden restos:
-   `grep -ril "plantilla\|template" . --exclude-dir=.git --exclude-dir=node_modules`
+10. Verifica que no queden restos:
+    `grep -ril "plantilla\|template" . --exclude-dir=.git --exclude-dir=node_modules`
+11. Pasa `/doctor` como última comprobación: entorno, variables, MCPs y tests. Si algo sale en
+    FALLO, arréglalo antes de dar la inicialización por terminada.
 
 ## Al terminar
 

.claude/settings.json

@@ -5,6 +5,10 @@
       "Bash(pnpm run *)",
       "Bash(pnpm dlx *)",
       "Bash(pnpm *)",
+      "Bash(node scripts/verificar-cobertura.mjs)",
+      "Bash(node -v)",
+      "Bash(node --version)",
+      "Bash(claude mcp list)",
       "Bash(git status)",
       "Bash(git diff*)",
       "Bash(git log*)",

.github/pull_request_template.md

@@ -7,6 +7,10 @@
 ## Motivación
 <!-- Por qué es necesario este cambio -->
 
+## Requisitos que cierra
+<!-- IDs del PRD que este cambio deja terminados: M-01, S-02…
+     Escribe "ninguno" si es un cambio interno (refactor, tooling, documentación). -->
+
 ## Tipo de cambio
 - [ ] Feature
 - [ ] Fix
@@ -15,8 +19,38 @@
 - [ ] Documentación
 - [ ] Configuración
 
+## Evidencia
+
+<!-- Pega aquí el comando que has ejecutado y su salida real, recortada a lo relevante.
+     No lo parafrasees: "los tests pasan" no es evidencia, la salida de los tests sí.
+     Si algo no se ha ejecutado, dilo y explica por qué en lugar de omitirlo.
+
+     Repasa lo que pegas antes de enviarlo: la salida de un comando puede arrastrar tokens,
+     cadenas de conexión o rutas locales. Un PR es público o, como mínimo, permanente.
+     Sustituye cualquier valor sensible por su nombre de variable. -->
+
+```
+$ pnpm test
+...
+```
+
+**Verificación de los requisitos:**
+
+<!-- Un renglón por cada requisito de la sección anterior. Si el requisito no se valida con un
+     test, di con qué se ha comprobado. Copia lo que ya declaraste en la ficha de docs/features/. -->
+
+| Requisito | Se validó con | Resultado |
+|-----------|---------------|-----------|
+|           |               |           |
+
 ## Checklist
+
+<!-- Marca solo lo que hayas verificado de verdad. Si un punto no aplica, déjalo sin marcar y
+     explica por qué en la descripción: un punto sin marcar y justificado es información útil;
+     uno marcado a ciegas es ruido que además tapa el problema. -->
+
 - [ ] Los documentos afectados en `docs/` están actualizados
+- [ ] La ficha de `docs/features/` está en estado **Verificada** (si este PR cierra una feature)
 - [ ] Hay una entrada en `changelog/` con este cambio
-- [ ] He probado el cambio en local antes de pedir review
+- [ ] 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

.github/workflows/cobertura.yml

@@ -0,0 +1,31 @@
+# Verifica que ninguna ficha de docs/features/ deje un requisito sin validación declarada,
+# y que los tests prometidos existan cuando la ficha dice estar Verificada.
+#
+# Se ejecuta en CI a propósito: el agente que rellena las tablas es el mismo que las cumpliría,
+# así que la comprobación tiene que vivir donde no pueda saltársela.
+
+name: Cobertura
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# El script solo lee archivos: no necesita escribir en el repositorio ni tocar nada
+# de la API. Acotarlo aquí limita el daño si una de las acciones se viera comprometida.
+permissions:
+  contents: read
+
+jobs:
+  verificar:
+    name: Tablas de cobertura
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      # Sin dependencias: el script usa solo módulos nativos de Node.
+      - run: node scripts/verificar-cobertura.mjs

.template/changelog/2026-08-18_12-39_verificabilidad-y-ciclo-de-feature.md

@@ -0,0 +1,100 @@
+# Verificabilidad: criterios de aceptación, ficha de feature y evidencia en el PR
+
+**Fecha:** 2026-08-18 12:39
+**Tipo:** Documentación
+**Requisitos:** Ninguno (cambio sobre el andamiaje de la plantilla)
+
+## Qué se hizo
+
+La plantilla cubría bien el principio de un proyecto (documentar antes de escribir) y el registro
+posterior (changelog, PR, mejoras), pero no decía nada sobre cómo se sabe que algo está terminado.
+"Hecho" quedaba en manos de quien lo declaraba. Este cambio cierra ese hueco en cuatro piezas.
+
+**1. Los requisitos del PRD ahora son comprobables.** Cada entrada MoSCoW de `docs/prd.md` lleva
+un identificador estable (`M-01`, `S-01`, `C-01`) y un criterio de aceptación en formato
+"Dado…, cuando…, entonces…", con la condición de que el "entonces" sea observable: un mensaje
+visible, una redirección, un registro creado. No un adjetivo. El ID es el nombre por el que ese
+requisito se cita después en la ficha, en el changelog, en el PR y en el nombre del test.
+
+**2. Nueva capa intermedia: `docs/features/`.** Entre la documentación del proyecto y el código no
+había ninguna unidad de trabajo. Ahora cada feature tiene su ficha —qué se construye, qué
+requisitos cierra, qué queda fuera— y sobre todo una **tabla de cobertura** con una regla: ningún
+requisito se queda sin tercera columna. O lleva la ruta del test que lo valida, o lleva
+`no verificable por interfaz: <razón concreta>` y cómo se comprueba entonces. La ficha tiene tres
+estados (Acordada / En construcción / Verificada) que se actualizan durante el trabajo, no al
+final, para poder retomar una feature en otra sesión sin reconstruir el contexto.
+
+**3. Los tests se escriben después de implementar.** Nueva sección en `docs/testing.md`. El
+compromiso de validar se adquiere antes (la tabla de cobertura); el test se escribe leyendo el
+código ya existente. Con las reglas que se derivan: verificar que el selector existe antes de
+asertar, añadir `data-testid` si no hay selector estable, una aserción por cada "entonces", y
+nunca arreglar un test que falla quitándole aserciones.
+
+**4. El PR se cierra con evidencia.** La plantilla de PR pide ahora los requisitos que cierra, una
+sección de evidencia con la salida real de los comandos ejecutados y una tabla de verificación por
+requisito. El checklist sigue estando, pero deja de ser la prueba: lo que prueba es la salida
+pegada.
+
+Además, dos cosas que faltaban y no dependen del stack:
+
+- **Tabla de proporcionalidad** en `CLAUDE.md`: qué documentos de `docs/` son obligatorios según
+  el tamaño del proyecto (sitio pequeño / producto / producto con negocio). Los que no aplican se
+  borran en la inicialización, no se dejan vacíos.
+- **Sección "Límites de ejecución"** en `CLAUDE.md`: todo se prueba en local, el agente no
+  despliega, los secretos no se imprimen ni se pasan por la línea de comandos, y nada destructivo
+  sin confirmación previa con el alcance exacto.
+
+Dos comandos nuevos: `/feature` (crea la ficha antes de construir) y `/doctor` (parte del estado
+de documentación, fichas a medias, entorno, variables, MCPs y tests; solo diagnostica, no arregla).
+
+## Qué se modificó
+
+- `CLAUDE.md` — nueva sección "Qué documentación necesita cada proyecto" con la tabla de tamaños;
+  nueva sección "Límites de ejecución"; nueva sección "Ciclo de trabajo de una feature"; paso 5 de
+  arranque (revisar fichas En construcción) y referencia a `/doctor`; campo `Requisitos` en el
+  formato de changelog; dos ejemplos nuevos en la lista de documentación afectada; pasos 2 y 4 del
+  protocolo de PRs (requisitos y evidencia) con el apartado "Por qué la evidencia y no la casilla";
+  dos reglas nuevas en "Qué NO hacer"; `docs/features/` en la estructura de carpetas; paso 7 del
+  checklist de inicialización (borrar documentos que no apliquen) y renumeración
+- `docs/prd.md` — IDs estables y criterios de aceptación en el bloque MoSCoW
+- `docs/features/README.md` — nuevo: formato de la ficha, regla de la tabla de cobertura y estados
+- `docs/testing.md` — nueva sección "Cuándo se escriben los tests"
+- `docs/architecture.md` — la estrategia de despliegue debe dejar escrito quién despliega
+- `.claude/commands/feature.md` — nuevo comando `/feature`
+- `.claude/commands/doctor.md` — nuevo comando `/doctor`
+- `.claude/commands/changelog.md` — campo `Requisitos` y comprobación del estado de la ficha
+- `.claude/commands/init-proyecto.md` — tabla de tamaños al completar docs; paso de borrado de
+  documentos que no apliquen; `/doctor` como comprobación final; renumeración
+- `.github/pull_request_template.md` — sección "Requisitos que cierra", sección "Evidencia" con
+  tabla de verificación, checklist reformulado
+- `changelog/README.md` — campo `Requisitos` en el formato, sincronizado con `CLAUDE.md`
+- `.claude/settings.json` — permitidas tres comprobaciones de solo lectura que necesita `/doctor`:
+  `node -v`, `node --version` y `claude mcp list`
+- `README.md` — `docs/features/` en el contenido; el protocolo pasa de 6 a 10 pasos; comandos
+  nuevos; filas de `docs/` y `docs/features/` en la tabla de adaptación; `/doctor` en el arranque
+
+## Por qué
+
+El protocolo anterior 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"; la salida de un comando sí.
+
+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. No había
+ningún artefacto que dijera "esto es lo que acordamos construir y así sabremos que funciona"
+**antes** del código, así que el alcance se renegociaba solo, sin que nadie lo notara.
+
+La regla de la tercera columna es la que sostiene el resto. Lo que se queda sin validar casi nunca
+se decide: se escurre. Nadie dice "este requisito no lo vamos a comprobar"; simplemente no aparece
+en ningún sitio y nadie lo echa de menos hasta que falla. Obligar a escribir la excepción convierte
+una omisión invisible en una frase que alguien puede leer y discutir.
+
+Lo de escribir los tests después de implementar viene del mismo sitio. Un test escrito durante la
+planificación apunta a selectores y rutas imaginados; cuando no coinciden con la realidad, casi
+nadie lo reescribe: se le van quitando aserciones hasta que pasa, y queda un test que no comprueba
+nada pero da luz verde. Es peor que no tenerlo, porque además tranquiliza.
+
+La tabla de proporcionalidad resuelve el problema opuesto. Exigir ocho documentos rellenos para una
+landing es la forma más rápida de que el protocolo se abandone en la segunda semana, y un protocolo
+abandonado no protege nada. La ceremonia tiene que escalar con lo que está en juego.