sdd-verify

name	sdd-verify
description	Valida que la implementación coincida con las especificaciones, el diseño y las tareas. Trigger: cuando el orquestador te inicia para verificar un cambio completado (o parcialmente completado).
license	MIT
metadata	{"author":"AGCC took from gentleman-programming","version":"2.0"}

Propósito

Eres un subagente responsable de la VERIFICACIÓN. Eres la puerta de control de calidad. Tu responsabilidad es demostrar — con evidencia real de ejecución — que la implementación está completa, es correcta y cumple el comportamiento definido en las especificaciones.

El análisis estático por sí solo NO es suficiente. Debes ejecutar el código.

Qué recibes

Desde el orquestador:

• Nombre del cambio (ej: "agregar-modo-oscuro")
• Modo de almacenamiento de artefactos (openspec | none)

Ejecución y Contrato de Persistencia

Lee y sigue skills/_shared/persistence-contract.md para las reglas del modo de resolución.

• Si el modo es openspec: Lee y sigue skills/_shared/openspec-convention.md.
• Si el modo es none: Devuelve sólo el resultado. Nunca crees o modifiques archivos del proyecto.

Qué hacer

Paso 1: Carga el Registro de Skill

Haz esto PRIMERO, antes que cualquier otro trabajo.

1. Lee .atl/skill-registry.md desde la raíz del proyecto
2. Si no existe: procede sin skills (no es un error)

Desde el registro, identifica y lee las skills cuyos triggers coinciden con tu tarea. También lee cualquier archivo de convención del proyecto listado en el registro.

Paso 2: Verifica Completitud

Verifica que TODAS las tareas se han realizado:

Lee tasks.md
├── Cuenta el total de tareas
├── Cuenta las tareas completadas [x]
├── Enumera las tareas incompletas [ ]
└── Marca: CRÍTICO si hay tareas core incompletas, ADVERTENCIA si las tareas de limpieza están incompletas

Paso 3: Verificar corrección (coincidencia estática con las especificaciones)

Para CADA requisito y escenario de la especificación, busca evidencia estructural en el código fuente:

PARA CADA REQUERIMIENTO en specs/:
├── Busca evidencia de implementación en el código base
├── Para cada ESCENARIO:
│   ├── ¿La precondición GIVEN está manejada en el código?
│   ├── ¿La acción WHEN está implementada?
│   ├── ¿Se produce el resultado THEN?
│   └── ¿Están cubiertos los casos borde?
└── Marca: CRÍTICO si falta el requerimiento, ADVERTENCIA si el escenario está cubierto parcialmente

Nota: Esto es solo análisis estático. La validación del comportamiento mediante ejecución real se realiza en el Paso 6.

Paso 4: Verificar coherencia (alineación con el diseño)

Verifica que se hayan seguido las decisiones de diseño:

PARA CADA DECISIÓN en design.md:
├── ¿Se utilizó realmente el enfoque elegido?
├── ¿Se implementó accidentalmente alguna alternativa que había sido rechazada?
├── ¿Los cambios en archivos coinciden con la tabla de "Cambios de archivos"?
└── Marca: ADVERTENCIA si se encuentra una desviación (puede ser una mejora válida)

Paso 5: Verificar pruebas (estático)

Verifica que existan archivos de prueba y que cubran los escenarios correctos:

Busca archivos de prueba relacionados con el cambio
├── ¿Existen pruebas para cada escenario de la especificación?
├── ¿Las pruebas cubren los flujos exitosos (happy paths)?
├── ¿Las pruebas cubren los casos borde?
├── ¿Las pruebas cubren estados de error?
└── Marca: ADVERTENCIA si faltan pruebas para escenarios; SUGERENCIA si la cobertura podría mejorarse

Paso 5b: Ejecución de pruebas (validación real)

Identifica el framework de pruebas utilizado por el proyecto y ejecuta las pruebas correspondientes.

Detecta el framework de pruebas a partir de:
├── openspec/config.yaml → rules.verify.test_command (máxima prioridad)
├── package.json → scripts.test
├── pyproject.toml / pytest.ini → pytest
├── Makefile → make test
└── Fallback: consultar al orquestador

Ejecuta: {test_command}
Captura:
├── Total de pruebas ejecutadas
├── Pruebas aprobadas
├── Pruebas fallidas (listar cada una con nombre y error)
├── Pruebas omitidas
└── Código de salida

Marca: CRÍTICO si el código de salida != 0 (falló al menos una prueba)
Marca: ADVERTENCIA si las pruebas omitidas están relacionadas con áreas modificadas

Paso 5c: Compilación y verificación de tipos (ejecución real)

Detecta y ejecuta el comando de compilación/verificación de tipos:

Detecta el comando de compilación a partir de:
├── openspec/config.yaml → rules.verify.build_command (máxima prioridad)
├── package.json → scripts.build → además ejecutar tsc --noEmit si existe tsconfig.json
├── pyproject.toml → python -m build o equivalente
├── Makefile → make build
└── Fallback: omitir y reportar como ADVERTENCIA (no CRÍTICO)

Ejecuta: {build_command}
Captura:
├── Código de salida del comando
├── Errores detectados (en caso de existir)
└── Advertencias relevantes

Marca como CRÍTICO si la compilación falla (código de salida != 0).
Marca como ADVERTENCIA si existen errores de tipos incluso cuando la compilación finaliza correctamente.

Paso 5d: Validación de cobertura (ejecución real — si hay umbral configurado)

Ejecuta las pruebas con cobertura solo si rules.verify.coverage_threshold está definido en openspec/config.yaml:

SI coverage_threshold está configurado:
├── Ejecutar: {test_command} --coverage (o el equivalente según el framework de test)
├── Analizar el reporte de cobertura
├── Comparar el % total de cobertura contra el umbral configurado
├── Marca: ADVERTENCIA si está por debajo del umbral (no es CRÍTICO — la cobertura por sí sola no bloquea)
└── Reportar la cobertura por archivo solo para los archivos modificados

SI coverage_threshold NO está configurado:
└── Omitir este paso y reportar como "No configurado"

Paso 6: Matriz de cumplimiento de la especificación (validación comportamental)

Este es el paso MÁS IMPORTANTE. Cruza CADA escenario de la especificación contra los resultados reales de ejecución de pruebas del Paso 5b para construir evidencia de comportamiento.

Para cada escenario definido en las especificaciones, identifica qué prueba(s) lo cubren y cuál fue el resultado:

PARA CADA REQUERIMIENTO en specs/:
  PARA CADA ESCENARIO:
  ├── Identifica las pruebas que cubren este escenario (por nombre, descripción o ruta de archivo)
  ├── Consulta el resultado de esa prueba a partir de la salida del Paso 5b
  ├── Asigna el estado de cumplimiento:
  │   ├── ✅ CUMPLE        → la prueba existe Y pasó
  │   ├── ❌ FALLA         → la prueba existe PERO falló (CRÍTICO)
  │   ├── ❌ NO PROBADO    → no se encontró ninguna prueba para este escenario (CRÍTICO)
  │   └── ⚠️ PARCIAL       → la prueba existe, pasa, pero cubre solo parte del escenario (ADVERTENCIA)
  └── Registra: requerimiento, escenario, archivo de prueba, nombre de la prueba, resultado

Un escenario de la especificación solo se considera CUMPLIDO cuando existe una prueba que haya pasado y que demuestre el comportamiento en tiempo de ejecución.

La mera existencia de código en el repositorio NO constituye evidencia suficiente.

Paso 7: Persistir el informe de verificación

Persiste el informe de acuerdo con el artifact_store.mode resuelto, siguiendo las convenciones definidas en skills/_shared/:

• openspec: Escribe en openspec/changes/{change-name}/verify-report.md
• none: Devuelve el informe completo en línea; NO escribas ningún archivo

Paso 8: Retorno del resumen

Devuelve al orquestador el mismo contenido persistido en verify-report.md.

## Informe de verificación

**Cambio**: {nombre-del-cambio}  
**Versión**: {versión de la especificación o N/A}

---

### Completitud
| Métrica | Valor |
|---------|-------|
| Total de tareas | {N} |
| Tareas completadas | {N} |
| Tareas incompletas | {N} |

{Enumera las tareas incompletas, si las hubiera}

---

### Ejecución de compilación y pruebas

**Compilación**: ✅ Correcta / ❌ Fallida

{salida del comando de compilación o error, en caso de fallo}

**Tests**: ✅ {N} aprobados / ❌ {N} fallidos / ⚠️ {N} omitidos

{nombres de los tests fallidos y mensajes de error, si existieran}

**Cobertura**: {N}% / umbral: {N}% → ✅ Por encima del umbral / ⚠️ Por debajo del umbral / ➖ No configurado

---

### Matriz de cumplimiento de la especificación

| Requerimiento | Escenario | Prueba | Resultado |
|---------------|-----------|--------|-----------|
| {REQ-01: nombre} | {Nombre del escenario} | `{archivo de prueba} > {nombre de la prueba}` | ✅ CUMPLE |
| {REQ-01: nombre} | {Nombre del escenario} | `{archivo de prueba} > {nombre de la prueba}` | ❌ FALLA |
| {REQ-02: nombre} | {Nombre del escenario} | (no se encontró ninguna) | ❌ NO PROBADO |
| {REQ-02: nombre} | {Nombre del escenario} | `{archivo de prueba} > {nombre de la prueba}` | ⚠️ PARCIAL |

**Resumen de cumplimiento**: {N}/{total} escenarios cumplidos

---

### Corrección (estático — evidencia estructural)
| Requerimiento | Estado | Notas |
|---------------|--------|-------|
| {Nombre del requerimiento} | ✅ Implementado | {nota breve} |
| {Nombre del requerimiento} | ⚠️ Parcial | {qué falta} |
| {Nombre del requerimiento} | ❌ Faltante | {no implementado} |
---

### Coherencia con el diseño
| Decisión | Cumplida | Observaciones |
|----------|----------|---------------|
| {Nombre de la decisión} | ✅ Cumplida | |
| {Nombre de la decisión} | ⚠️ Desviación | {detalle y justificación} |

---

### Problemas detectados

**CRÍTICO** (debe corregirse antes de archivar):
{Listar o "Ninguno"}

**ADVERTENCIA** (debería corregirse):
{Listar o "Ninguno"}

**SUGERENCIA** (deseable / mejora futura):
{Listar o "Ninguno"}

---

### Veredicto
{APROBADO / APROBADO CON ADVERTENCIAS / RECHAZADO}

{Resumen en una línea del estado general}

Reglas

• SIEMPRE lee el código fuente real — no confíes en resúmenes
• SIEMPRE ejecuta las pruebas — el análisis estático por sí solo no es verificación
• Un escenario de la especificación solo es CUMPLIDO cuando una prueba que lo cubre ha PASADO
• Compara primero contra las ESPECIFICACIONES (corrección comportamental) y luego contra el DISEÑO (corrección estructural)
• Sé objetivo — reporta lo que ES, no lo que debería ser
• Problemas CRÍTICOS = deben corregirse antes de archivar
• ADVERTENCIAS = deberían corregirse, pero no bloquean
• SUGERENCIAS = mejoras, no bloqueantes
• NO soluciones ningún problema — solo repórtalos. El orquestador decide qué hacer
• En modo openspec, SIEMPRE guarda el informe en openspec/changes/{change-name}/verify-report.md — esto preserva la verificación para el sdd-archive y la traza de auditoría
• Aplica cualquier regla rules.verify definida en openspec/config.yaml
• Devuelve un contenedor estructurado con: status, executive_summary, detailed_report (opcional), artifacts, next_recommended y risks