michangarrito/orchestration/_archive/_definitions/protocols/CAPVED-CYCLE.md

tipo	nivel	ssot	audiencia	proposito	actualizado
especificacion-tecnica	2-tecnico	/orchestration/directivas/principios/PRINCIPIO-CAPVED.md	agentes IA, sistemas automaticos	Especificacion tecnica del protocolo CAPVED	2026-01-16

PROTOCOLO: CAPVED-CYCLE

Versión: 1.0.0 Alias: @DEF_CAPVED Fecha: 2026-01-16 Sistema: SIMCO v4.0.0 SSOT: PRINCIPIO-CAPVED.md

---

RESUMEN

CAPVED es el ciclo de vida obligatorio para toda tarea en el workspace. Define 6 fases secuenciales que aseguran calidad, trazabilidad y documentación completa.

C → A → P → V → E → D
│   │   │   │   │   │
│   │   │   │   │   └─ DOCUMENTACIÓN (Registrar, trazar, propagar)
│   │   │   │   └───── EJECUCIÓN (Implementar cambios)
│   │   │   └───────── VALIDACIÓN (Gate pre-ejecución)
│   │   └───────────── PLANEACIÓN (Desglosar subtareas)
│   └───────────────── ANÁLISIS (Mapear impacto)
└───────────────────── CONTEXTO (Clasificar y vincular)

---

FASES DEL CICLO

FASE C - CONTEXTO

Objetivo: Clasificar tarea y vincular con proyecto/workspace.

actividades:
  - Identificar tipo de tarea (feature/fix/refactor/analysis)
  - Identificar proyecto(s) involucrado(s)
  - Identificar nivel (workspace/proyecto/módulo)
  - Cargar contexto requerido según perfil
  - Vincular con épica/user story si aplica

salidas:
  - Tipo de tarea identificado
  - Proyecto(s) identificado(s)
  - Contexto mínimo viable cargado
  - Vinculación establecida

criterios_completitud:
  - Proyecto claramente identificado
  - Tipo de tarea determinado
  - Contexto base cargado

FASE A - ANÁLISIS

Objetivo: Mapear impacto, dependencias y riesgos.

actividades:
  - Ejecutar TRIGGER-ANTI-DUPLICACION si es creación
  - Ejecutar TRIGGER-ANALISIS-DEPENDENCIAS si es modificación
  - Identificar archivos afectados
  - Mapear dependientes (quién usa lo que modifico)
  - Mapear dependencias (qué usa lo que modifico)
  - Evaluar riesgos y complejidad

salidas:
  - Mapa de impacto
  - Lista de dependientes
  - Lista de dependencias
  - Evaluación de riesgos
  - Complejidad estimada

criterios_completitud:
  - Impacto mapeado
  - Dependencias identificadas
  - Riesgos evaluados

FASE P - PLANEACIÓN

Objetivo: Desglosar en subtareas por dominio.

actividades:
  - Crear lista de subtareas específicas
  - Ordenar por dependencia (DDL → BE → FE)
  - Identificar subtareas paralelizables
  - Asignar perfil responsable por subtarea
  - Definir criterios de aceptación por subtarea

salidas:
  - Lista de subtareas (ST-001, ST-002, ...)
  - Orden de ejecución
  - Asignación de perfiles
  - Criterios de aceptación

criterios_completitud:
  - Subtareas definidas
  - Orden establecido
  - Criterios claros

FASE V - VALIDACIÓN (Gate)

Objetivo: Verificar antes de ejecutar.

actividades:
  - Verificar que plan cubre todo el impacto
  - Verificar que no hay scope creep
  - Verificar que dependencias están resueltas
  - Verificar que hay capacidad de rollback
  - Confirmar alineación con estándares

salidas:
  - Checklist de validación completado
  - Decisión GO/NO-GO

criterios_completitud:
  - Todas las verificaciones pasadas
  - Decisión GO documentada

decision:
  GO: "Continuar a Fase E"
  NO-GO: "Regresar a Fase A o P según hallazgo"

FASE E - EJECUCIÓN

Objetivo: Implementar cambios según plan.

actividades:
  - Ejecutar subtareas en orden
  - Validar cada subtarea (build/lint/test)
  - Crear commits atómicos por subtarea
  - Documentar problemas encontrados
  - Escalar si hay bloqueos

salidas:
  - Código implementado
  - Commits realizados
  - Validaciones pasadas
  - Problemas documentados

criterios_completitud:
  - Todas las subtareas completadas
  - Build pasa
  - Lint pasa
  - Tests pasan (si existen)

FASE D - DOCUMENTACIÓN

Objetivo: Registrar, trazar y propagar.

IMPORTANTE: Esta fase tiene dos sub-fases en orden estricto:

1. D1 - Gobernanza (BLOQUEANTE)
2. D2 - Técnica (después de gobernanza)

actividades:
  # D1 - GOBERNANZA (PRIMERO - BLOQUEANTE)
  d1_gobernanza:
    - Crear carpeta de tarea: orchestration/tareas/TASK-{ID}/
    - Completar METADATA.yml
    - Documentar 01-CONTEXTO.md (qué y por qué)
    - Documentar 05-EJECUCION.md (cómo y qué problemas)
    - Documentar 06-DOCUMENTACION.md (resumen y referencias)
    - Actualizar orchestration/tareas/_INDEX.yml
    - Actualizar traza de agente (opcional pero recomendado)

  # D2 - TÉCNICA (después de gobernanza)
  d2_tecnica:
    - Actualizar inventarios afectados
    - Evaluar propagación (TRIGGER-PROPAGACION-AUTOMATICA)
    - Crear/actualizar documentación técnica si aplica

salidas:
  # Gobernanza
  - Carpeta de tarea con documentación completa
  - _INDEX.yml actualizado
  # Técnica
  - Inventarios actualizados
  - Propagación evaluada/ejecutada

criterios_completitud:
  # Gobernanza (BLOQUEANTE)
  - Carpeta TASK-{ID}/ existe
  - METADATA.yml completo
  - Fases C, E, D documentadas
  - _INDEX.yml actualizado
  # Técnica
  - Inventarios al día
  - Propagación evaluada

validacion:
  checklist: "@DEF_CHK_GOB (gobernanza) + @DEF_CHK_POST (técnica)"
  orden: "Gobernanza PRIMERO, luego técnica"

---

MODOS DE EJECUCIÓN

MODE-FULL (Por defecto)

fases: [C, A, P, V, E, D]
uso: "Features, bug fixes, refactorizaciones, cambios BD"
alias: "@FULL"

MODE-QUICK

fases: [E, D]
uso: "Typos, fixes menores, updates de deps, config simple"
alias: "@QUICK"
condicion: "Cambio trivial sin riesgo de impacto"

MODE-ANALYSIS

fases: [C, A, P]
uso: "Investigación, auditoría, exploración, propuestas"
alias: "@ANALYSIS"
nota: "No modifica código"

MODE-PROPAGATION

fases: [C, A, P, E, V, D]  # Por cada proyecto destino
uso: "Propagar cambio existente a proyectos relacionados"
alias: "@PROPAGATE"

---

INTEGRACIÓN CON TRIGGERS

triggers_por_fase:
  A:
    - TRIGGER-ANTI-DUPLICACION (si creación)
    - TRIGGER-ANALISIS-DEPENDENCIAS (si modificación)
  V:
    - TRIGGER-DUPLICADOS (si se detectan)
  D:
    - TRIGGER-PROPAGACION-AUTOMATICA
    - TRIGGER-DOCUMENTACION-OBLIGATORIA

---

INTEGRACIÓN CON GOBERNANZA

OBLIGATORIO: Toda tarea que complete el ciclo CAPVED DEBE crear documentación de gobernanza. BLOQUEANTE: Sin gobernanza, la tarea NO está completada.

gobernanza:
  checklist: "@DEF_CHK_GOB"

  pasos:
    1_carpeta_tarea:
      accion: "Crear orchestration/tareas/TASK-{ID}/"
      bloqueante: true

    2_metadata:
      accion: "Completar METADATA.yml con todos los campos obligatorios"
      bloqueante: true

    3_fases_minimas:
      accion: "Documentar 01-CONTEXTO.md, 05-EJECUCION.md, 06-DOCUMENTACION.md"
      bloqueante: true

    4_actualizar_indices:
      accion: "Actualizar orchestration/tareas/_INDEX.yml"
      bloqueante: true

    5_traza_agente:
      accion: "Actualizar traza del agente ejecutor"
      bloqueante: false
      nota: "Recomendado pero no bloquea"

  si_falta_gobernanza:
    mensaje: "❌ TAREA NO COMPLETADA - Falta documentación de gobernanza"
    accion: "BLOQUEAR hasta completar"
    referencia: "@DEF_CHK_GOB"

  recordatorio_todolist: |
    Al iniciar cualquier tarea, el TodoList DEBE incluir como último item:
    - content: "Crear documentación de gobernanza (TASK-{ID})"
      status: "pending"
      activeForm: "Documentando gobernanza"    

---

VALIDACIONES POR DOMINIO

Backend (NestJS)

npm run build    # DEBE pasar
npm run lint     # DEBE pasar
npm run test     # Si existen, DEBEN pasar

Frontend (React)

npm run build    # DEBE pasar
npm run lint     # DEBE pasar
npm run typecheck # DEBE pasar

Database (PostgreSQL)

./scripts/recreate-database.sh  # DEBE ejecutar sin errores

---

REFERENCIAS

Alias	Descripción
@DEF_CAPVED	Este protocolo
@PRINCIPIOS/PRINCIPIO-CAPVED.md	Principio base
@SIMCO/SIMCO-TAREA.md	Punto de entrada
@TRIGGER-DOC	Documentación obligatoria

---

Versión: 1.0.0 | Sistema: SIMCO v4.0.0 | Tipo: Protocolo Base