From a7575d6096b7d4a01489da2a9c230c88fe4a8a9a Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Sun, 18 Jan 2026 09:35:59 -0600 Subject: [PATCH] [GOVERNANCE] feat: Add _definitions, checklists CAPVED, _SSOT, and task templates Propagated via automated script (scripts/propagate-governance.sh): - orchestration/_definitions/: canonical definitions - orchestration/directivas/checklists/: CAPVED phase checklists - docs/_SSOT/: Single Source of Truth - orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/ Configured as STANDALONE project Co-Authored-By: Claude Opus 4.5 --- docs/_SSOT/EPIC-INDEX.yml | 21 ++ docs/_SSOT/README.md | 28 ++ docs/_SSOT/TRACEABILITY-MASTER.yml | 23 ++ orchestration/_definitions/_INDEX.yml | 63 ++++ .../checklists/CHECKLIST-GOBERNANZA-TAREA.md | 223 +++++++++++ .../checklists/CHECKLIST-POST-TASK.md | 244 ++++++++++++ .../checklists/CHECKLIST-PRE-CREATE.md | 107 ++++++ .../checklists/CHECKLIST-PRE-MODIFY.md | 149 ++++++++ .../_definitions/protocols/CAPVED-CYCLE.md | 347 +++++++++++++++++ .../_definitions/protocols/CCA-PROTOCOL.md | 245 ++++++++++++ .../validations/VALIDATION-BACKEND.md | 81 ++++ .../validations/VALIDATION-DDL.md | 89 +++++ .../validations/VALIDATION-FRONTEND.md | 81 ++++ .../directivas/checklists/CHECKLIST-CIERRE.md | 185 +++++++++ .../directivas/checklists/CHECKLIST-FASE-A.md | 74 ++++ .../directivas/checklists/CHECKLIST-FASE-C.md | 77 ++++ .../directivas/checklists/CHECKLIST-FASE-D.md | 111 ++++++ .../directivas/checklists/CHECKLIST-FASE-E.md | 184 +++++++++ .../directivas/checklists/CHECKLIST-FASE-P.md | 75 ++++ .../directivas/checklists/CHECKLIST-FASE-V.md | 81 ++++ orchestration/directivas/checklists/README.md | 100 +++++ .../TASK-TEMPLATE-UNIFIED/LESSONS-LEARNED.yml | 184 +++++++++ .../TASK-TEMPLATE-UNIFIED/METADATA.yml | 230 ++++++++++++ .../TASK-TEMPLATE-UNIFIED/README.md | 129 +++++++ .../TASK-TEMPLATE-UNIFIED/SUBTASKS.yml | 353 ++++++++++++++++++ 25 files changed, 3484 insertions(+) create mode 100644 docs/_SSOT/EPIC-INDEX.yml create mode 100644 docs/_SSOT/README.md create mode 100644 docs/_SSOT/TRACEABILITY-MASTER.yml create mode 100644 orchestration/_definitions/_INDEX.yml create mode 100644 orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md create mode 100644 orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md create mode 100644 orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md create mode 100644 orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md create mode 100644 orchestration/_definitions/protocols/CAPVED-CYCLE.md create mode 100644 orchestration/_definitions/protocols/CCA-PROTOCOL.md create mode 100644 orchestration/_definitions/validations/VALIDATION-BACKEND.md create mode 100644 orchestration/_definitions/validations/VALIDATION-DDL.md create mode 100644 orchestration/_definitions/validations/VALIDATION-FRONTEND.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-CIERRE.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-FASE-A.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-FASE-C.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-FASE-D.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-FASE-E.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-FASE-P.md create mode 100644 orchestration/directivas/checklists/CHECKLIST-FASE-V.md create mode 100644 orchestration/directivas/checklists/README.md create mode 100644 orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/LESSONS-LEARNED.yml create mode 100644 orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/METADATA.yml create mode 100644 orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/README.md create mode 100644 orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/SUBTASKS.yml diff --git a/docs/_SSOT/EPIC-INDEX.yml b/docs/_SSOT/EPIC-INDEX.yml new file mode 100644 index 000000000..98b1a72ac --- /dev/null +++ b/docs/_SSOT/EPIC-INDEX.yml @@ -0,0 +1,21 @@ +# EPIC-INDEX: Indice Maestro de Epicas MICHANGARRITO +# Version: 1.0.0 +# Actualizado: 2026-01-18 + +metadata: + version: "1.0.0" + created: "2026-01-18" + last_updated: "2026-01-18" + project: "michangarrito" + + + total_epics: 0 + +statistics: + by_status: + completed: 0 + in_progress: 0 + planned: 0 + +epics: + # PENDIENTE: Poblar con epicas reales diff --git a/docs/_SSOT/README.md b/docs/_SSOT/README.md new file mode 100644 index 000000000..0d1957f04 --- /dev/null +++ b/docs/_SSOT/README.md @@ -0,0 +1,28 @@ +# Single Source of Truth (SSOT) - MICHANGARRITO + +**Version:** 1.0.0 +**Fecha:** 2026-01-18 +**Proyecto:** michangarrito +**Sistema:** SIMCO v4.0.0 + + +--- + +## Proposito + +Este directorio contiene los indices y registros maestros del proyecto. +Son la **Fuente Unica de Verdad** para trazabilidad, requerimientos y completitud. + +--- + +## Archivos SSOT + +| Archivo | Descripcion | Estado | +|---------|-------------|--------| +| EPIC-INDEX.yml | Indice de epicas | ACTIVO | +| TRACEABILITY-MASTER.yml | Trazabilidad maestra | ACTIVO | + +--- + +**Creado:** 2026-01-18 +**Mantenido por:** @MICHANGARRITO_ORCHESTRATOR diff --git a/docs/_SSOT/TRACEABILITY-MASTER.yml b/docs/_SSOT/TRACEABILITY-MASTER.yml new file mode 100644 index 000000000..bea0d0ae4 --- /dev/null +++ b/docs/_SSOT/TRACEABILITY-MASTER.yml @@ -0,0 +1,23 @@ +# TRACEABILITY-MASTER: Trazabilidad Maestra MICHANGARRITO +# Version: 1.0.0 +# Actualizado: 2026-01-18 + +metadata: + version: "1.0.0" + created: "2026-01-18" + last_updated: "2026-01-18" + project: "michangarrito" + type: "STANDALONE" + + propagates_to: [] + +modules: + + + + + own: + # PENDIENTE: Definir modulos propios + +traceability_matrix: + # PENDIENTE: Completar matriz diff --git a/orchestration/_definitions/_INDEX.yml b/orchestration/_definitions/_INDEX.yml new file mode 100644 index 000000000..c265adb86 --- /dev/null +++ b/orchestration/_definitions/_INDEX.yml @@ -0,0 +1,63 @@ +# ═══════════════════════════════════════════════════════════════════════════════ +# ÍNDICE DE DEFINICIONES CANÓNICAS - MICHANGARRITO +# ═══════════════════════════════════════════════════════════════════════════════ + +version: "1.0.0" +created: "2026-01-18" +updated: "2026-01-18" +maintained_by: "@WS_ORCHESTRATOR" +propagated_from: "erp-core/orchestration/_definitions/" +role: "STANDALONE" + +protocols: + CCA-PROTOCOL: + alias: "@DEF_CCA" + path: "protocols/CCA-PROTOCOL.md" + estado: "PROPAGADO" + CAPVED-CYCLE: + alias: "@DEF_CAPVED" + path: "protocols/CAPVED-CYCLE.md" + estado: "PROPAGADO" + +validations: + VALIDATION-BACKEND: + alias: "@DEF_VAL_BE" + path: "validations/VALIDATION-BACKEND.md" + estado: "PROPAGADO" + VALIDATION-FRONTEND: + alias: "@DEF_VAL_FE" + path: "validations/VALIDATION-FRONTEND.md" + estado: "PROPAGADO" + VALIDATION-DDL: + alias: "@DEF_VAL_DDL" + path: "validations/VALIDATION-DDL.md" + estado: "PROPAGADO" + +checklists: + CHECKLIST-GOBERNANZA-TAREA: + alias: "@DEF_CHK_GOB" + path: "checklists/CHECKLIST-GOBERNANZA-TAREA.md" + estado: "PROPAGADO" + CHECKLIST-POST-TASK: + alias: "@DEF_CHK_POST" + path: "checklists/CHECKLIST-POST-TASK.md" + estado: "PROPAGADO" + CHECKLIST-PRE-CREATE: + alias: "@DEF_CHK_CREATE" + path: "checklists/CHECKLIST-PRE-CREATE.md" + estado: "PROPAGADO" + CHECKLIST-PRE-MODIFY: + alias: "@DEF_CHK_MODIFY" + path: "checklists/CHECKLIST-PRE-MODIFY.md" + estado: "PROPAGADO" + +statistics: + total_definitions: 9 + propagated: 9 + +standalone_config: + role: "STANDALONE" + inherits_from: "workspace" + propagates_to: [] + sync_strategy: "MANUAL" + nota: "Proyecto independiente - actualizar manualmente desde workspace" diff --git a/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md b/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md new file mode 100644 index 000000000..e71dd474c --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md @@ -0,0 +1,223 @@ +# CHECKLIST: GOBERNANZA DE TAREA + +**Versión:** 1.0.0 +**Alias:** @DEF_CHK_GOB +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 +**Prioridad:** P0 - BLOQUEANTE + +--- + +## PROPÓSITO + +Este checklist es **OBLIGATORIO** y **BLOQUEANTE** para toda tarea que se marque como completada. +Debe ejecutarse ANTES de cualquier otra validación post-tarea. + +> **REGLA:** Sin gobernanza documentada, la tarea NO está completada. + +--- + +## SECUENCIA DE EJECUCIÓN + +``` +TAREA FINALIZA EJECUCIÓN + │ + ▼ +┌─────────────────────────────┐ +│ CHECKLIST-GOBERNANZA-TAREA │ ← PRIMERO (este checklist) +│ (BLOQUEANTE) │ +└─────────────┬───────────────┘ + │ + ▼ + ¿Todos los items pasan? + / \ + Sí No + │ │ + ▼ ▼ +CHECKLIST-POST-TASK BLOQUEAR +(validaciones (no continuar + técnicas) hasta resolver) +``` + +--- + +## CHECKLIST (8 Items) + +### 1. Carpeta de Tarea + +```markdown +[ ] Existe carpeta: orchestration/tareas/TASK-{YYYY-MM-DD}-{NNN}/ +``` + +**Si no existe:** +```bash +# Crear carpeta +mkdir -p orchestration/tareas/TASK-$(date +%Y-%m-%d)-00X + +# Copiar templates +cp -r orchestration/tareas/_templates/TASK-TEMPLATE/* orchestration/tareas/TASK-$(date +%Y-%m-%d)-00X/ +``` + +### 2. METADATA.yml + +```markdown +[ ] METADATA.yml existe y tiene campos obligatorios: + [ ] task_id + [ ] identificacion.titulo + [ ] identificacion.tipo + [ ] responsabilidad.agente_responsable + [ ] alcance.nivel + [ ] temporalidad.fecha_inicio + [ ] estado.actual = "completada" + [ ] artefactos.archivos_creados (lista) + [ ] artefactos.archivos_modificados (lista) +``` + +### 3. Fase C - Contexto (OBLIGATORIA) + +```markdown +[ ] 01-CONTEXTO.md existe y documenta: + [ ] Qué se solicitó + [ ] Por qué se necesita + [ ] Proyecto/módulo afectado + [ ] Contexto cargado +``` + +### 4. Fase E - Ejecución (OBLIGATORIA) + +```markdown +[ ] 05-EJECUCION.md existe y documenta: + [ ] Subtareas ejecutadas + [ ] Archivos creados/modificados + [ ] Validaciones ejecutadas + [ ] Problemas encontrados y cómo se resolvieron +``` + +### 5. Fase D - Documentación (OBLIGATORIA) + +```markdown +[ ] 06-DOCUMENTACION.md existe y documenta: + [ ] Resumen de cambios + [ ] Inventarios actualizados + [ ] Propagación evaluada + [ ] Referencias actualizadas +``` + +### 6. Índice de Tareas + +```markdown +[ ] orchestration/tareas/_INDEX.yml actualizado: + [ ] Estadísticas actualizadas + [ ] Tarea en historial_por_fecha + [ ] Tarea en por_proyecto + [ ] Tarea en por_agente + [ ] Tarea en por_tipo +``` + +### 7. Traza de Agente (Recomendado) + +```markdown +[ ] orchestration/agents/trazas/TRAZA-AGENTE-{PERFIL}.md actualizada + O +[ ] Excepción documentada en METADATA.yml +``` + +### 8. Validación Final + +```markdown +[ ] Carpeta de tarea contiene mínimo: + - METADATA.yml (completo) + - 01-CONTEXTO.md (documentado) + - 05-EJECUCION.md (documentado) + - 06-DOCUMENTACION.md (documentado) +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Continuar con CHECKLIST-POST-TASK" + nota: "Gobernanza validada" + +SI_FALLA_CUALQUIER_ITEM: + accion: "BLOQUEAR" + mensaje: | + ❌ GOBERNANZA INCOMPLETA + + La tarea NO puede marcarse como completada. + Items faltantes: + - {lista de items faltantes} + + Acciones requeridas: + 1. Completar items faltantes + 2. Re-ejecutar este checklist + 3. Continuar con validaciones técnicas +``` + +--- + +## TEMPLATE RÁPIDO + +Para crear documentación de gobernanza rápidamente: + +```bash +# Variables +TASK_ID="TASK-$(date +%Y-%m-%d)-00X" +TASK_DIR="orchestration/tareas/$TASK_ID" + +# 1. Crear estructura +mkdir -p $TASK_DIR +cp orchestration/tareas/_templates/TASK-TEMPLATE/* $TASK_DIR/ + +# 2. Completar METADATA.yml +# 3. Documentar 01-CONTEXTO.md +# 4. Documentar 05-EJECUCION.md +# 5. Documentar 06-DOCUMENTACION.md +# 6. Actualizar _INDEX.yml +``` + +--- + +## INTEGRACIÓN CON TODOLIST + +Al iniciar cualquier tarea, el TodoList DEBE incluir: + +```yaml +todos: + # ... otras tareas ... + + # SIEMPRE al final: + - content: "Crear documentación de gobernanza (TASK-{ID})" + status: "pending" + activeForm: "Documentando gobernanza" +``` + +--- + +## USO + +```yaml +# En cualquier perfil de agente: +al_completar_trabajo_tecnico: + - Cargar: "@DEF_CHK_GOB" + - Ejecutar: "8 items de gobernanza" + - Si pasa: "Continuar con @DEF_CHK_POST" + - Si falla: "Completar gobernanza primero" +``` + +--- + +## REFERENCIAS + +| Alias | Descripción | +|-------|-------------| +| @DEF_CHK_GOB | Este checklist | +| @DEF_CHK_POST | Checklist post-tarea (validaciones técnicas) | +| @TRIGGER-DOC | Trigger de documentación obligatoria | +| @TAREAS | Directorio de tareas | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist Bloqueante diff --git a/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md b/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md new file mode 100644 index 000000000..e1d036a3c --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md @@ -0,0 +1,244 @@ +# CHECKLIST: POST-TASK + +**Versión:** 1.1.0 +**Alias:** @DEF_CHK_POST +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 + +--- + +## PROPÓSITO + +Verificaciones obligatorias DESPUÉS de completar cualquier tarea, antes de marcarla como terminada. + +--- + +## SECUENCIA OBLIGATORIA + +``` +TAREA FINALIZA EJECUCIÓN + │ + ▼ +┌─────────────────────────────┐ +│ 0. GOBERNANZA │ ← PRIMERO (BLOQUEANTE) +│ (@DEF_CHK_GOB) │ +└─────────────┬───────────────┘ + ¿Pasa? + / \ + No Sí + │ │ + BLOQUEAR ▼ + ┌─────────────────────────────┐ + │ 1-7. VALIDACIONES TÉCNICAS │ + │ (este checklist) │ + └─────────────────────────────┘ +``` + +--- + +## CHECKLIST + +### 0. Gobernanza de Tarea (BLOQUEANTE - EJECUTAR PRIMERO) + +> **OBLIGATORIO:** Ejecutar @DEF_CHK_GOB antes de continuar. + +```markdown +[ ] CHECKLIST-GOBERNANZA-TAREA.md ejecutado y PASADO + - Carpeta de tarea existe + - METADATA.yml completo + - Fases C, E, D documentadas + - _INDEX.yml actualizado + +SI NO PASA: DETENER. Completar gobernanza primero. +``` + +--- + +### 1. Validaciones Técnicas + +#### Backend (si aplica) +```markdown +[ ] npm run build - PASA +[ ] npm run lint - PASA +[ ] npm run test - PASA (si existen tests) +[ ] Servidor inicia sin errores +``` + +#### Frontend (si aplica) +```markdown +[ ] npm run build - PASA +[ ] npm run lint - PASA +[ ] npm run typecheck - PASA +[ ] Aplicación renderiza sin errores +``` + +#### Database (si aplica) +```markdown +[ ] DDL ejecuta sin errores +[ ] Datos de prueba cargan correctamente +[ ] Constraints funcionan como esperado +``` + +### 2. Coherencia Entre Capas (TRIGGER-COHERENCIA-CAPAS) + +```markdown +## DDL ↔ Backend +[ ] Toda tabla DDL tiene entity correspondiente (o excepción documentada) +[ ] Toda entity tiene tabla DDL correspondiente (o es View/Embeddable) +[ ] Campos de entity coinciden exactamente con columnas de tabla +[ ] Tipos TypeScript son compatibles con tipos PostgreSQL +[ ] Todo schema tiene al menos un módulo backend (o está marcado PLANNED) + +## Backend ↔ Frontend (si aplica) +[ ] Todo endpoint consumido tiene implementación en backend +[ ] Si hay nuevo endpoint: está documentado en Swagger +[ ] Si hay nuevo componente: está integrado donde corresponde + +## Verificación de Excepciones +[ ] Tablas M:N sin entity están documentadas en ENTITIES-CATALOG sección "Relaciones" +[ ] View entities (@ViewEntity) están documentadas como tal +[ ] Schemas PLANNED tienen fecha estimada de implementación +``` + +### 3. Actualización de Inventarios (TRIGGER-INVENTARIOS-SINCRONIZADOS) + +```markdown +## Sincronización Obligatoria +[ ] DATABASE_INVENTORY.yml actualizado (si cambió BD) + - Conteo de schemas correcto + - Conteo de tablas correcto + - Nuevos objetos agregados +[ ] BACKEND_INVENTORY.yml actualizado (si cambió BE) + - Conteo de módulos correcto + - Conteo de entities correcto + - Conteo de services correcto +[ ] FRONTEND_INVENTORY.yml actualizado (si cambió FE) + - Conteo de componentes correcto + - Conteo de páginas correcto +[ ] MASTER_INVENTORY.yml actualizado con totales + +## Verificación de Cobertura +[ ] Cobertura de inventarios = 100% +[ ] Timestamp de actualización = fecha de hoy +[ ] sync_status = "SYNCED" +``` + +### 4. Actualización de Trazas + +```markdown +[ ] Traza de tarea actualizada +[ ] Traza de agente actualizada +[ ] PROXIMA-ACCION.md actualizado +[ ] Commits con mensajes descriptivos +``` + +### 5. Documentación + +```markdown +[ ] README actualizado (si cambió significativamente) +[ ] Documentación técnica actualizada (si aplica) +[ ] ADR creado (si fue decisión arquitectural) +[ ] Comentarios en código donde la lógica no es obvia +``` + +### 6. Sistema de Gobernanza + +```markdown +[ ] Carpeta de tarea creada: orchestration/tareas/TASK-{ID}/ +[ ] METADATA.yml completado +[ ] Fases mínimas documentadas (C, E, D) +[ ] _INDEX.yml de tareas actualizado +[ ] Traza de agente actualizada +``` + +### 7. Evaluación de Propagación + +```markdown +[ ] ¿Cambio debe propagarse a otros proyectos? +[ ] Si es erp-core: ¿propagar a verticales? +[ ] Si es shared/catalog: ¿notificar proyectos que lo usan? +[ ] Si es security fix: ¿propagar inmediatamente? +``` + +--- + +## CRITERIOS DE COMPLETITUD + +### Tarea Completada SI: + +```yaml +obligatorio: + - Todas las validaciones técnicas pasan + - Inventarios actualizados + - Trazas actualizadas + - Documentación de gobernanza creada + +recomendado: + - Documentación técnica actualizada + - Tests agregados/actualizados + - Propagación evaluada +``` + +### Tarea NO Completada SI: + +```yaml +bloqueantes: + - Build falla + - Lint falla + - Tests fallan + - Inventarios no actualizados + - Sin documentación de gobernanza +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Marcar tarea como COMPLETADA" + documentar: "Resumen en METADATA.yml" + actualizar: "_INDEX.yml con estado COMPLETADO" + +SI_FALLA_VALIDACION: + accion: "MANTENER como EN_PROGRESO" + corregir: "Resolver validaciones fallidas" + reintentar: "Ejecutar checklist de nuevo" + +SI_FALTA_DOCUMENTACION: + accion: "MANTENER como EN_PROGRESO" + completar: "Documentación faltante" + nota: "Tarea no está completa sin documentación" +``` + +--- + +## USO + +```yaml +# En cualquier perfil de agente: +al_completar_tarea: + - Cargar: "@DEF_CHK_POST" + - Ejecutar: "Checklist completo" + - Si pasa: "Marcar tarea como completada" + - Si falla: "Resolver antes de marcar completada" +``` + +--- + +## INTEGRACIÓN CON TRIGGER-DOC + +Este checklist se activa junto con `TRIGGER-DOCUMENTACION-OBLIGATORIA.md` al intentar completar una tarea. + +```yaml +secuencia: + 1: "Agente intenta marcar tarea como completada" + 2: "TRIGGER-DOC se activa" + 3: "Se ejecuta CHECKLIST-POST-TASK" + 4: "Si pasa: tarea se marca completada" + 5: "Si falla: tarea permanece en progreso" +``` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist diff --git a/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md b/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md new file mode 100644 index 000000000..7dac19cc2 --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md @@ -0,0 +1,107 @@ +# CHECKLIST: PRE-CREATE + +**Versión:** 1.0.0 +**Alias:** @DEF_CHK_CREATE +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 + +--- + +## PROPÓSITO + +Verificaciones obligatorias ANTES de crear cualquier objeto nuevo (tabla, entity, service, componente, etc.). + +--- + +## CHECKLIST + +### 1. Verificación Anti-Duplicación + +```markdown +[ ] Buscar en catálogo compartido (shared/catalog/CATALOG-INDEX.yml) +[ ] Buscar en inventario del proyecto (orchestration/inventarios/) +[ ] Buscar archivos similares con nombre parecido +[ ] Buscar funcionalidad similar en módulos existentes +[ ] Confirmar que NO existe funcionalidad equivalente +``` + +### 2. Verificación de Dependencias + +```markdown +[ ] Identificar de qué depende el nuevo objeto +[ ] Verificar que las dependencias existen +[ ] Si depende de DDL: tabla existe en base de datos +[ ] Si depende de entity: entity existe en backend +[ ] Si depende de endpoint: endpoint existe y funciona +``` + +### 3. Verificación de Ubicación + +```markdown +[ ] Identificar módulo/carpeta correcta según estándares +[ ] Verificar que la ruta sigue convenciones del proyecto +[ ] Confirmar que no hay conflicto de nombres +[ ] Verificar permisos de escritura en la ubicación +``` + +### 4. Verificación de Nomenclatura + +```markdown +[ ] Nombre sigue convenciones del proyecto +[ ] Nombre es descriptivo y no ambiguo +[ ] Prefijos/sufijos correctos según tipo de archivo +[ ] Formato de archivo correcto (PascalCase, kebab-case, etc.) +``` + +### 5. Verificación de Coherencia + +```markdown +[ ] Nuevo objeto es coherente con arquitectura existente +[ ] No introduce acoplamiento innecesario +[ ] Sigue patrones establecidos del proyecto +[ ] No duplica responsabilidades de otros objetos +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Proceder con creación" + siguiente: "Ejecutar SIMCO-CREAR.md" + +SI_FALLA_DUPLICACION: + accion: "DETENER - Evaluar uso del existente" + opciones: + - "Usar objeto existente" + - "Extender objeto existente" + - "Justificar creación de nuevo (documentar razón)" + +SI_FALLA_DEPENDENCIA: + accion: "DETENER - Resolver dependencia primero" + opciones: + - "Delegar creación de dependencia" + - "Crear dependencia primero" + - "Replanificar orden de tareas" + +SI_FALLA_NOMENCLATURA: + accion: "Corregir nombre antes de crear" + consultar: "@SIMCO/SIMCO-NOMENCLATURA.md" +``` + +--- + +## USO + +```yaml +# En perfil de agente: +antes_de_crear: + - Cargar: "@DEF_CHK_CREATE" + - Ejecutar: "Checklist completo" + - Documentar: "Resultado en traza" +``` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist diff --git a/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md b/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md new file mode 100644 index 000000000..edc8d54fd --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md @@ -0,0 +1,149 @@ +# CHECKLIST: PRE-MODIFY + +**Versión:** 1.0.0 +**Alias:** @DEF_CHK_MODIFY +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 + +--- + +## PROPÓSITO + +Verificaciones obligatorias ANTES de modificar cualquier archivo existente. + +--- + +## CHECKLIST + +### 1. Análisis de Dependientes + +```markdown +[ ] Identificar archivos que IMPORTAN el archivo a modificar +[ ] Listar todos los dependientes encontrados +[ ] Evaluar impacto del cambio en cada dependiente +[ ] Clasificar cambio como: aditivo | modificación | breaking +``` + +### 2. Análisis de Dependencias + +```markdown +[ ] Identificar archivos que el archivo IMPORTA +[ ] Verificar que las dependencias siguen siendo válidas post-cambio +[ ] Identificar si el cambio requiere actualizar dependencias +``` + +### 3. Evaluación de Impacto + +```markdown +[ ] Determinar alcance: local | módulo | proyecto | workspace +[ ] Identificar capas afectadas: DDL | BE | FE +[ ] Evaluar si cambio requiere migración de datos +[ ] Evaluar si cambio rompe compatibilidad hacia atrás +``` + +### 4. Plan de Actualización + +```markdown +[ ] Si hay dependientes afectados: incluir en plan de subtareas +[ ] Ordenar actualizaciones por dependencia (de más interno a más externo) +[ ] Identificar tests que deben actualizarse +[ ] Identificar documentación que debe actualizarse +``` + +### 5. Verificación de Seguridad + +```markdown +[ ] Cambio no introduce vulnerabilidades de seguridad +[ ] Cambio no expone datos sensibles +[ ] Cambio mantiene validaciones existentes +[ ] Si es API: cambio no rompe contratos existentes +``` + +### 6. Estrategia de Rollback + +```markdown +[ ] Identificar cómo revertir el cambio si falla +[ ] Confirmar que existe backup o commit previo +[ ] Documentar pasos de rollback si son complejos +``` + +--- + +## CLASIFICACIÓN DE CAMBIOS + +### Cambio Aditivo (BAJO RIESGO) +```yaml +caracteristicas: + - Agregar campo/método nuevo + - Agregar endpoint nuevo + - No modifica comportamiento existente +acciones: + - Actualizar dependientes que usarán lo nuevo + - Validación estándar +``` + +### Cambio de Modificación (MEDIO RIESGO) +```yaml +caracteristicas: + - Cambiar implementación interna + - Cambiar tipos de datos + - Renombrar elementos +acciones: + - Actualizar TODOS los dependientes + - Validación exhaustiva + - Pruebas de regresión +``` + +### Cambio Breaking (ALTO RIESGO) +```yaml +caracteristicas: + - Eliminar campo/método + - Cambiar firma de función/endpoint + - Cambiar comportamiento de API +acciones: + - DETENER y evaluar con Tech-Leader + - Plan de migración obligatorio + - Comunicar a equipos afectados +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Proceder con modificación" + siguiente: "Ejecutar SIMCO-MODIFICAR.md" + incluir: "Actualización de dependientes en plan" + +SI_CAMBIO_BREAKING: + accion: "ESCALAR a Tech-Leader" + documentar: + - Razón del cambio breaking + - Alternativas evaluadas + - Plan de migración propuesto + +SI_IMPACTO_ALTO: + accion: "Solicitar revisión antes de proceder" + documentar: + - Alcance del impacto + - Dependientes afectados + - Plan de actualización +``` + +--- + +## USO + +```yaml +# En perfil de agente: +antes_de_modificar: + - Cargar: "@DEF_CHK_MODIFY" + - Ejecutar: "Checklist completo" + - Documentar: "Resultado en traza" + - Si breaking: "Escalar antes de continuar" +``` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist diff --git a/orchestration/_definitions/protocols/CAPVED-CYCLE.md b/orchestration/_definitions/protocols/CAPVED-CYCLE.md new file mode 100644 index 000000000..9f9a1cbc7 --- /dev/null +++ b/orchestration/_definitions/protocols/CAPVED-CYCLE.md @@ -0,0 +1,347 @@ +--- +tipo: especificacion-tecnica +nivel: 2-tecnico +ssot: /orchestration/directivas/principios/PRINCIPIO-CAPVED.md +audiencia: agentes IA, sistemas automaticos +proposito: Especificacion tecnica del protocolo CAPVED +actualizado: 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](/orchestration/directivas/principios/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. + +```yaml +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. + +```yaml +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. + +```yaml +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. + +```yaml +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. + +```yaml +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) + +```yaml +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) + +```yaml +fases: [C, A, P, V, E, D] +uso: "Features, bug fixes, refactorizaciones, cambios BD" +alias: "@FULL" +``` + +### MODE-QUICK + +```yaml +fases: [E, D] +uso: "Typos, fixes menores, updates de deps, config simple" +alias: "@QUICK" +condicion: "Cambio trivial sin riesgo de impacto" +``` + +### MODE-ANALYSIS + +```yaml +fases: [C, A, P] +uso: "Investigación, auditoría, exploración, propuestas" +alias: "@ANALYSIS" +nota: "No modifica código" +``` + +### MODE-PROPAGATION + +```yaml +fases: [C, A, P, E, V, D] # Por cada proyecto destino +uso: "Propagar cambio existente a proyectos relacionados" +alias: "@PROPAGATE" +``` + +--- + +## INTEGRACIÓN CON TRIGGERS + +```yaml +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. + +```yaml +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) +```bash +npm run build # DEBE pasar +npm run lint # DEBE pasar +npm run test # Si existen, DEBEN pasar +``` + +### Frontend (React) +```bash +npm run build # DEBE pasar +npm run lint # DEBE pasar +npm run typecheck # DEBE pasar +``` + +### Database (PostgreSQL) +```bash +./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 diff --git a/orchestration/_definitions/protocols/CCA-PROTOCOL.md b/orchestration/_definitions/protocols/CCA-PROTOCOL.md new file mode 100644 index 000000000..3f35e6340 --- /dev/null +++ b/orchestration/_definitions/protocols/CCA-PROTOCOL.md @@ -0,0 +1,245 @@ +# Protocolo CCA - Carga de Contexto Automática +## Definición Canónica (Fuente Única de Verdad) + +**Versión:** 1.0.0 +**Fecha:** 2026-01-16 +**Alias:** @DEF_CCA +**Tipo:** Definición Canónica + +--- + +## PROPÓSITO + +Este documento es la **ÚNICA** fuente de verdad para el Protocolo CCA. +Todos los perfiles de agentes deben **REFERENCIAR** este archivo, no copiar su contenido. + +--- + +## USO EN PERFILES + +```markdown +## PROTOCOLO CCA +> Definición: @DEF_CCA +> Variante: {dominio} + +### Extensiones Específicas +[Solo contenido específico del dominio] +``` + +--- + +## PROTOCOLO BASE + +> **ANTES de cualquier acción, ejecutar Carga de Contexto Automática** + +```yaml +# Al recibir: "Serás {PERFIL}-Agent en {PROYECTO} para {TAREA}" + +# ═══════════════════════════════════════════════════════════════ +# PASO 0: IDENTIFICAR NIVEL (OBLIGATORIO PRIMERO) +# ═══════════════════════════════════════════════════════════════ +PASO_0_IDENTIFICAR_NIVEL: + leer: "orchestration/directivas/simco/SIMCO-NIVELES.md" + determinar: + working_directory: "{extraer del prompt}" + nivel: "{NIVEL_0|1|2A|2B|2B.1|2B.2|3}" + orchestration_path: "{calcular según nivel}" + propagate_to: ["{niveles superiores si aplica}"] + registrar: + nivel_actual: "{nivel identificado}" + ruta_inventario: "{orchestration_path}/inventarios/" + ruta_traza: "{orchestration_path}/trazas/" + +# ═══════════════════════════════════════════════════════════════ +# PASO 1: IDENTIFICAR CONTEXTO +# ═══════════════════════════════════════════════════════════════ +PASO_1_IDENTIFICAR: + perfil: "{PERFIL}" # Nombre del perfil activo + proyecto: "{PROYECTO}" # Extraer del prompt + tarea: "{TAREA}" # Extraer del prompt + operacion: "CREAR | MODIFICAR | VALIDAR | DOCUMENTAR | BUSCAR" + dominio: "{DOMINIO}" # BACKEND | FRONTEND | DDL | DEVOPS | ML | etc. + +# ═══════════════════════════════════════════════════════════════ +# PASO 2: CARGAR CONTEXTO CORE (SIEMPRE) +# ═══════════════════════════════════════════════════════════════ +PASO_2_CARGAR_CORE: + leer_obligatorio: + # Catálogo primero (evitar duplicados) + - shared/catalog/CATALOG-INDEX.yml + + # Principios fundamentales + - orchestration/directivas/principios/PRINCIPIO-CAPVED.md + - orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md + - orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md + - orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md + - orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md + + # Índices y referencias + - orchestration/directivas/simco/_INDEX.md + - orchestration/directivas/simco/SIMCO-TAREA.md + - orchestration/referencias/ALIASES.yml + +# ═══════════════════════════════════════════════════════════════ +# PASO 3: CARGAR CONTEXTO DEL PROYECTO +# ═══════════════════════════════════════════════════════════════ +PASO_3_CARGAR_PROYECTO: + leer_obligatorio: + - projects/{PROYECTO}/orchestration/00-guidelines/CONTEXTO-PROYECTO.md + - projects/{PROYECTO}/orchestration/PROXIMA-ACCION.md + + leer_segun_dominio: + # Ver sección VARIANTES POR DOMINIO + +# ═══════════════════════════════════════════════════════════════ +# PASO 4: CARGAR DIRECTIVAS DE OPERACIÓN +# ═══════════════════════════════════════════════════════════════ +PASO_4_CARGAR_OPERACION: + verificar_catalogo_primero: + - "grep -i '{funcionalidad}' @CATALOG_INDEX" + - si_existe: "Seguir @REUTILIZAR en lugar de crear" + + segun_operacion: + crear: ["SIMCO-CREAR.md", "SIMCO-{DOMINIO}.md"] + modificar: ["SIMCO-MODIFICAR.md", "SIMCO-{DOMINIO}.md"] + validar: ["SIMCO-VALIDAR.md"] + documentar: ["SIMCO-DOCUMENTAR.md"] + buscar: ["SIMCO-BUSCAR.md"] + +# ═══════════════════════════════════════════════════════════════ +# PASO 5: CARGAR CONTEXTO ESPECÍFICO DE TAREA +# ═══════════════════════════════════════════════════════════════ +PASO_5_CARGAR_TAREA: + - "Documentación relevante en docs/" + - "Código existente similar (patrones)" + - "Archivos relacionados con la tarea" + - "Identificar dependencias" + +# ═══════════════════════════════════════════════════════════════ +# PASO 6: VERIFICAR DEPENDENCIAS +# ═══════════════════════════════════════════════════════════════ +PASO_6_VERIFICAR_DEPENDENCIAS: + si_dependencia_no_existe: + accion: "DELEGAR al agente correspondiente" + no_continuar_hasta: "Dependencia resuelta" + + dependencias_por_dominio: + backend: + requiere: "Tablas DDL existen" + delegar_a: "@PERFIL_DATABASE" + frontend: + requiere: "Endpoints API existen" + delegar_a: "@PERFIL_BACKEND" + devops: + requiere: "Código funcional existe" + delegar_a: "@PERFIL_BACKEND o @PERFIL_FRONTEND" + +# ═══════════════════════════════════════════════════════════════ +# RESULTADO +# ═══════════════════════════════════════════════════════════════ +RESULTADO: "READY_TO_EXECUTE - Contexto completo cargado" +``` + +--- + +## VARIANTES POR DOMINIO + +### #backend +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/BACKEND_INVENTORY.yml + - projects/{PROYECTO}/orchestration/inventarios/DATABASE_INVENTORY.yml + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_entity: [SIMCO-CREAR.md, SIMCO-BACKEND.md] + crear_service: [SIMCO-CREAR.md, SIMCO-BACKEND.md] + crear_controller: [SIMCO-CREAR.md, SIMCO-BACKEND.md] + crear_dto: [SIMCO-CREAR.md, SIMCO-BACKEND.md] +``` + +### #frontend +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/FRONTEND_INVENTORY.yml + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_componente: [SIMCO-CREAR.md, SIMCO-FRONTEND.md] + crear_hook: [SIMCO-CREAR.md, SIMCO-FRONTEND.md] + crear_page: [SIMCO-CREAR.md, SIMCO-FRONTEND.md] +``` + +### #ddl +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/DATABASE_INVENTORY.yml + - projects/{PROYECTO}/ddl/ # Esquemas existentes + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_tabla: [SIMCO-CREAR.md, SIMCO-DDL.md] + crear_funcion: [SIMCO-CREAR.md, SIMCO-DDL.md] + crear_trigger: [SIMCO-CREAR.md, SIMCO-DDL.md] + crear_rls: [SIMCO-CREAR.md, SIMCO-DDL.md] +``` + +### #devops +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/docker-compose.yml + - projects/{PROYECTO}/.env.example + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_dockerfile: [SIMCO-CREAR.md, SIMCO-DEVOPS.md] + crear_pipeline: [SIMCO-CREAR.md, SIMCO-DEVOPS.md] +``` + +### #ml +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/ML_INVENTORY.yml + - projects/{PROYECTO}/models/ + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_modelo: [SIMCO-CREAR.md, SIMCO-ML.md] + crear_pipeline_ml: [SIMCO-CREAR.md, SIMCO-ML.md] +``` + +--- + +## VERSIÓN LIGERA (SUBAGENTES) + +Para subagentes con tareas específicas, usar versión reducida: + +```yaml +# CCA Ligero - Solo para subagentes +CCA_LIGHT: + PASO_1: "Identificar perfil, proyecto, tarea" + PASO_2: "Cargar ALIASES.yml" + PASO_3: "Cargar inventario del dominio" + PASO_4: "Cargar SIMCO de operación" + RESULTADO: "READY_TO_EXECUTE" +``` + +Ver también: @DEF_CCA_LIGHT + +--- + +## REFERENCIAS + +- **Perfiles que usan este protocolo:** Todos los perfiles en agents/perfiles/ +- **Directiva relacionada:** SIMCO-INICIALIZACION.md +- **Versión ligera:** @DEF_CCA_LIGHT + +--- + +**Última actualización:** 2026-01-16 +**Mantenido por:** @WS_ORCHESTRATOR diff --git a/orchestration/_definitions/validations/VALIDATION-BACKEND.md b/orchestration/_definitions/validations/VALIDATION-BACKEND.md new file mode 100644 index 000000000..8c15c7528 --- /dev/null +++ b/orchestration/_definitions/validations/VALIDATION-BACKEND.md @@ -0,0 +1,81 @@ +# Validación Backend - NestJS/TypeScript +## Definición Canónica + +**Alias:** @DEF_VAL_BE +**Dominio:** Backend NestJS/TypeScript + +--- + +## COMANDOS OBLIGATORIOS + +```bash +# ANTES de marcar tarea como completada: +npm run build # DEBE pasar sin errores +npm run lint # DEBE pasar sin errores +npm run test # Si existen tests, DEBEN pasar +``` + +## CRITERIOS DE ACEPTACIÓN + +```yaml +build: + resultado: "Compila sin errores" + archivos_generados: "dist/" + sin_warnings_criticos: true + +lint: + resultado: "0 errores de ESLint" + warnings_permitidos: "Solo menores" + reglas_obligatorias: + - "@typescript-eslint/no-explicit-any" + - "@typescript-eslint/no-unused-vars" + +test: + resultado: "100% tests pasan" + coverage_minimo: "70% (si configurado)" + nuevos_tests: "Crear para código nuevo" +``` + +## VALIDACIONES ADICIONALES + +```yaml +entities: + - "Alineadas con DDL (nombres, tipos)" + - "Relaciones correctamente definidas" + - "Decoradores TypeORM correctos" + +services: + - "Inyección de dependencias correcta" + - "Manejo de errores implementado" + - "Transacciones donde aplique" + +controllers: + - "Decoradores Swagger completos" + - "Validación de DTOs" + - "Guards aplicados" + +dtos: + - "class-validator decoradores" + - "Tipos correctos" + - "Documentación Swagger" +``` + +## ERRORES COMUNES + +```yaml +- error: "Cannot find module" + causa: "Import incorrecto o dependencia faltante" + solucion: "Verificar rutas y npm install" + +- error: "Type X is not assignable to type Y" + causa: "Tipos incompatibles" + solucion: "Alinear tipos con DDL/interfaces" + +- error: "Circular dependency" + causa: "Módulos se importan mutuamente" + solucion: "Extraer a módulo compartido o forwardRef" +``` + +--- + +**Referencia:** @PERFIL_BACKEND, @SIMCO_BACKEND diff --git a/orchestration/_definitions/validations/VALIDATION-DDL.md b/orchestration/_definitions/validations/VALIDATION-DDL.md new file mode 100644 index 000000000..4a08f8053 --- /dev/null +++ b/orchestration/_definitions/validations/VALIDATION-DDL.md @@ -0,0 +1,89 @@ +# Validación DDL - PostgreSQL +## Definición Canónica + +**Alias:** @DEF_VAL_DDL +**Dominio:** Database DDL PostgreSQL + +--- + +## COMANDOS OBLIGATORIOS + +```bash +# ANTES de marcar tarea como completada: + +# 1. Validar sintaxis SQL +psql -h localhost -U postgres -d {DB} -f {archivo}.sql --set ON_ERROR_STOP=1 + +# 2. Verificar que no hay errores +echo $? # Debe ser 0 + +# 3. Si existe script de recreación: +./scripts/recreate-database.sh # DEBE ejecutar sin errores +``` + +## CRITERIOS DE ACEPTACIÓN + +```yaml +sintaxis: + resultado: "SQL ejecuta sin errores" + encoding: "UTF-8" + schema_correcto: true + +convenciones: + tablas: "snake_case, plural (users, products)" + columnas: "snake_case (created_at, user_id)" + constraints: "{tabla}_{columna}_{tipo} (users_email_unique)" + indices: "idx_{tabla}_{columnas}" + foreign_keys: "fk_{tabla_origen}_{tabla_destino}" + +integridad: + - "Primary keys definidas" + - "Foreign keys con ON DELETE/UPDATE" + - "NOT NULL donde aplique" + - "DEFAULT values apropiados" + - "CHECK constraints donde necesario" +``` + +## VALIDACIONES ADICIONALES + +```yaml +tablas: + - "Columnas id, created_at, updated_at presentes" + - "Tipos de datos apropiados" + - "Índices en columnas de búsqueda frecuente" + +rls_policies: + - "Habilitado en tablas multi-tenant" + - "Políticas para SELECT, INSERT, UPDATE, DELETE" + - "Usando tenant_id del contexto" + +funciones: + - "SECURITY DEFINER/INVOKER correcto" + - "Manejo de errores (EXCEPTION)" + - "Documentación en comentarios" + +triggers: + - "Timing correcto (BEFORE/AFTER)" + - "Operaciones correctas (INSERT/UPDATE/DELETE)" + - "Función trigger existe" +``` + +## ERRORES COMUNES + +```yaml +- error: "relation already exists" + causa: "Tabla/objeto ya existe" + solucion: "Usar IF NOT EXISTS o DROP primero" + +- error: "foreign key constraint violation" + causa: "Referencia a registro inexistente" + solucion: "Verificar orden de inserción o CASCADE" + +- error: "column does not exist" + causa: "Nombre de columna incorrecto" + solucion: "Verificar nombres y comillas" +``` + +--- + +**Referencia:** @PERFIL_DATABASE, @SIMCO_DDL diff --git a/orchestration/_definitions/validations/VALIDATION-FRONTEND.md b/orchestration/_definitions/validations/VALIDATION-FRONTEND.md new file mode 100644 index 000000000..794cf41c5 --- /dev/null +++ b/orchestration/_definitions/validations/VALIDATION-FRONTEND.md @@ -0,0 +1,81 @@ +# Validación Frontend - React/TypeScript +## Definición Canónica + +**Alias:** @DEF_VAL_FE +**Dominio:** Frontend React/TypeScript + +--- + +## COMANDOS OBLIGATORIOS + +```bash +# ANTES de marcar tarea como completada: +npm run build # DEBE pasar sin errores +npm run lint # DEBE pasar sin errores +npm run typecheck # DEBE pasar sin errores (tsc --noEmit) +``` + +## CRITERIOS DE ACEPTACIÓN + +```yaml +build: + resultado: "Build de producción exitoso" + sin_warnings_criticos: true + bundle_size: "Monitorear incrementos grandes" + +lint: + resultado: "0 errores de ESLint" + reglas_react: + - "react-hooks/rules-of-hooks" + - "react-hooks/exhaustive-deps" + +typecheck: + resultado: "0 errores de TypeScript" + strict_mode: true + no_any_implicito: true +``` + +## VALIDACIONES ADICIONALES + +```yaml +componentes: + - "Props tipadas correctamente" + - "Keys únicas en listas" + - "Manejo de loading/error states" + - "Accesibilidad básica (aria labels)" + +hooks: + - "Dependencias completas en useEffect" + - "Cleanup en useEffect si necesario" + - "useMemo/useCallback donde aplique" + +estado: + - "Estado mínimo necesario" + - "Derivar datos cuando posible" + - "Zustand/Context correctamente usado" + +api: + - "Manejo de errores de red" + - "Estados de carga" + - "Cancelación de requests" +``` + +## ERRORES COMUNES + +```yaml +- error: "React Hook useEffect has missing dependency" + causa: "Dependencia no incluida en array" + solucion: "Agregar dependencia o usar useCallback" + +- error: "Cannot read property of undefined" + causa: "Datos async no disponibles" + solucion: "Optional chaining o loading state" + +- error: "Each child should have unique key" + causa: "Key faltante o duplicada en map()" + solucion: "Usar ID único como key" +``` + +--- + +**Referencia:** @PERFIL_FRONTEND, @SIMCO_FRONTEND diff --git a/orchestration/directivas/checklists/CHECKLIST-CIERRE.md b/orchestration/directivas/checklists/CHECKLIST-CIERRE.md new file mode 100644 index 000000000..3a865228a --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-CIERRE.md @@ -0,0 +1,185 @@ +# CHECKLIST-CIERRE: Gate Final de Tarea + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-CIERRE`, `@DEF_CHK_POST` + +## Proposito + +Gate BLOQUEANTE final antes de marcar una tarea como completada. +**NINGUN ITEM PUEDE QUEDAR SIN MARCAR.** + +--- + +## SECCION 1: GOBERNANZA (OBLIGATORIO) + +### Estructura de Tarea + +- [ ] Carpeta de tarea existe: `orchestration/tareas/TASK-YYYY-MM-DD-NNN/` +- [ ] METADATA.yml completo y correcto +- [ ] SUBTASKS.yml con summary actualizado +- [ ] LESSONS-LEARNED.yml iniciado (minimo summary) + +### Registro en Indices + +- [ ] Entrada en `orchestration/tareas/_INDEX.yml` +- [ ] Status: completed +- [ ] Path correcto + +--- + +## SECCION 2: VALIDACIONES TECNICAS (OBLIGATORIO) + +### Build (segun dominios afectados) + +- [ ] Backend: `npm run build` PASA +- [ ] Frontend: `npm run build` PASA +- [ ] Database: `recreate-database.sh` exitoso + +### Lint + +- [ ] Backend: `npm run lint` PASA (< 5 warnings nuevos) +- [ ] Frontend: `npm run lint` PASA + +### Tests + +- [ ] Backend: `npm run test` PASA (tests existentes) +- [ ] Frontend: `npm run test` PASA (si existen) +- [ ] Ningun test nuevo falla + +### TypeCheck + +- [ ] Frontend: `npm run typecheck` PASA + +--- + +## SECCION 3: COHERENCIA ENTRE CAPAS (OBLIGATORIO) + +### DDL -> Backend + +- [ ] Toda tabla nueva tiene entity correspondiente +- [ ] Campos de entity coinciden con columnas de tabla +- [ ] Tipos TypeScript compatibles con tipos PostgreSQL +- [ ] EXCEPCIONES documentadas (tablas M:N, audit, etc.) + +### Backend -> Frontend (si aplica) + +- [ ] Endpoints nuevos documentados +- [ ] DTOs expuestos correctamente +- [ ] Frontend consume endpoints correctamente + +--- + +## SECCION 4: INVENTARIOS (OBLIGATORIO) + +### Actualizacion + +- [ ] DATABASE_INVENTORY.yml actualizado (si cambio DDL) +- [ ] BACKEND_INVENTORY.yml actualizado (si cambio backend) +- [ ] FRONTEND_INVENTORY.yml actualizado (si cambio frontend) +- [ ] MASTER_INVENTORY.yml actualizado con totales + +### Cobertura + +- [ ] Cobertura de inventarios = 100% (sin objetos sin documentar) + +--- + +## SECCION 5: TRAZAS (OBLIGATORIO) + +### Archivos de Traza + +- [ ] TRAZA-TAREAS-*.md correspondiente actualizado +- [ ] Cambios documentados con fecha y descripcion + +### SSOT (si nueva funcionalidad) + +- [ ] TRACEABILITY-MASTER.yml actualizado +- [ ] EPIC-INDEX.yml actualizado si cambio estado de epica + +--- + +## SECCION 6: PROPAGACION (EVALUACION) + +### Evaluacion + +- [ ] Se evaluo si cambio requiere propagacion a otros proyectos +- [ ] Si SI requiere: plan de propagacion documentado +- [ ] Si NO requiere: marcado como N/A + +--- + +## SECCION 7: GIT (OBLIGATORIO) + +### Estado del Repositorio + +- [ ] `git status` = "working tree clean" +- [ ] Todos los cambios commiteados +- [ ] Commit message sigue convencion: `[TASK-ID] tipo: descripcion` + +### Push (segun politica) + +- [ ] Cambios pusheados a remote (si aplica) +- [ ] `git log origin/main..HEAD` vacio (si aplica) + +--- + +## RESUMEN DE VALIDACION + +| Seccion | Estado | +|---------|--------| +| 1. Gobernanza | [ ] PASA | +| 2. Validaciones Tecnicas | [ ] PASA | +| 3. Coherencia Entre Capas | [ ] PASA | +| 4. Inventarios | [ ] PASA | +| 5. Trazas | [ ] PASA | +| 6. Propagacion | [ ] EVALUADO | +| 7. Git | [ ] PASA | + +--- + +## CRITERIO FINAL + +### TAREA COMPLETADA si: +- [ ] **TODAS** las secciones marcadas como PASA/EVALUADO +- [ ] **NINGUN** item critico sin marcar +- [ ] **NINGUN** build/lint/test fallando + +### TAREA NO COMPLETADA si: +- Cualquier seccion falla +- Items pendientes sin justificacion +- Errores de build/lint/test + +--- + +## ACCION POST-CIERRE + +Si PASA: +1. Marcar METADATA.yml status: completed +2. Marcar SUBTASKS.yml todas completadas +3. Actualizar _INDEX.yml con status: completed +4. Commit final con mensaje: `[TASK-ID] docs: cierre de tarea` + +Si NO PASA: +1. Identificar items faltantes +2. Completar items +3. Re-ejecutar este checklist + +--- + +## NOTAS + +Este checklist integra: +- `@TRIGGER_CIERRE` - Trigger de cierre obligatorio +- `@TRIGGER_COHERENCIA` - Coherencia entre capas +- `@TRIGGER_INVENTARIOS` - Inventarios sincronizados + +**NO se puede marcar tarea como completada sin pasar este checklist.** + +--- + +## Referencias + +- Trigger Cierre: `orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md` +- Trigger Coherencia: `orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md` +- Trigger Inventarios: `orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md` diff --git a/orchestration/directivas/checklists/CHECKLIST-FASE-A.md b/orchestration/directivas/checklists/CHECKLIST-FASE-A.md new file mode 100644 index 000000000..8c47afc9e --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-FASE-A.md @@ -0,0 +1,74 @@ +# CHECKLIST-FASE-A: Gate de Analisis + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-ANALISIS` + +## Proposito + +Validar que el analisis de impacto y dependencias esta completo antes de planificar. + +--- + +## Checklist + +### Analisis de Dependencias + +- [ ] Identificados archivos que IMPORTAN los archivos a modificar (dependientes) +- [ ] Identificados archivos que los archivos a modificar IMPORTAN (dependencias) +- [ ] Evaluado impacto del cambio en dependientes +- [ ] Si hay cambios breaking: incluidos en el alcance + +### Analisis de Codigo Existente + +- [ ] Leido y entendido el codigo actual a modificar +- [ ] Identificados patrones existentes a seguir +- [ ] Identificados anti-patrones a evitar +- [ ] Documentado estado actual (si es complejo) + +### Analisis de Riesgos + +- [ ] Riesgos tecnicos identificados +- [ ] Riesgos de integracion identificados +- [ ] Plan de mitigacion para riesgos altos +- [ ] Riesgos documentados en METADATA.yml o SUBTASKS.yml + +### Validacion de Alcance + +- [ ] Alcance claramente definido (que SI y que NO incluye) +- [ ] Criterios de aceptacion identificados +- [ ] Entregables esperados listados + +### Dependencias de Tareas + +- [ ] Tareas previas requeridas identificadas +- [ ] Tareas bloqueadas por esta identificadas +- [ ] Si hay bloqueantes: documentados y plan de resolucion + +--- + +## Criterios de Paso + +**PASA** si: +- Dependencias de codigo mapeadas +- Riesgos identificados (aunque sea "sin riesgos significativos") +- Alcance definido + +**NO PASA** si: +- No se leyó el codigo existente +- Cambios breaking no identificados +- Riesgos no evaluados + +--- + +## Siguiente Fase + +Si PASA: Continuar a **Fase P: Plan** +Si NO PASA: Completar analisis faltante + +--- + +## Referencias + +- Trigger Analisis Dependencias: `orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md` +- DEPENDENCY-GRAPH: `orchestration/trazabilidad/DEPENDENCY-GRAPH-VISUAL.yml` diff --git a/orchestration/directivas/checklists/CHECKLIST-FASE-C.md b/orchestration/directivas/checklists/CHECKLIST-FASE-C.md new file mode 100644 index 000000000..0aaa62da6 --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-FASE-C.md @@ -0,0 +1,77 @@ +# CHECKLIST-FASE-C: Gate de Contexto + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-CONTEXTO` + +## Proposito + +Validar que la tarea esta correctamente contextualizada antes de pasar a Analisis. + +--- + +## Checklist + +### Identificacion + +- [ ] Task ID asignado (TASK-YYYY-MM-DD-NNN) +- [ ] Titulo descriptivo definido +- [ ] Tipo de tarea clasificado (feature/bug/refactor/audit/migration/documentation) +- [ ] Prioridad asignada (P0-P3) +- [ ] Epic relacionada identificada (si aplica) + +### Vinculacion con Requerimientos + +- [ ] RF (Requerimientos Funcionales) vinculados +- [ ] ET (Especificaciones Tecnicas) vinculados +- [ ] US (User Stories) vinculadas +- [ ] Verificado que RF existe en documentacion (no inventado) + +### Verificacion Anti-Duplicacion + +- [ ] Consultado `shared/catalog/CATALOG-INDEX.yml` por funcionalidad similar +- [ ] Verificado en inventarios que no existe duplicado +- [ ] Si existe similar: documentado diferencia o marcado como extension + +### Dominios Afectados + +- [ ] Identificados dominios que seran afectados: + - [ ] Database (DDL, seeds, migrations) + - [ ] Backend (entities, services, controllers) + - [ ] Frontend (components, pages, stores) + - [ ] Documentation (inventarios, trazas) + +### Metadata Inicial + +- [ ] METADATA.yml creado con campos basicos +- [ ] SUBTASKS.yml inicializado (puede estar vacio) + +--- + +## Criterios de Paso + +**PASA** si: +- Todos los items de "Identificacion" estan marcados +- Al menos 1 RF o US esta vinculado +- Verificacion anti-duplicacion realizada +- Dominios afectados identificados + +**NO PASA** si: +- Tarea no tiene RF/ET/US vinculados y no es tarea tecnica +- No se verifico duplicacion +- Dominios no estan claros + +--- + +## Siguiente Fase + +Si PASA: Continuar a **Fase A: Analisis** +Si NO PASA: Completar items faltantes antes de continuar + +--- + +## Referencias + +- Trigger Anti-Duplicacion: `orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md` +- SSOT: `docs/_SSOT/REQUIREMENTS-INDEX.yml` +- Catalogo: `shared/catalog/CATALOG-INDEX.yml` diff --git a/orchestration/directivas/checklists/CHECKLIST-FASE-D.md b/orchestration/directivas/checklists/CHECKLIST-FASE-D.md new file mode 100644 index 000000000..5707e5b82 --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-FASE-D.md @@ -0,0 +1,111 @@ +# CHECKLIST-FASE-D: Gate de Documentacion + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-DOCUMENTACION` + +## Proposito + +Validar que toda la documentacion necesaria ha sido actualizada. + +--- + +## Checklist + +### Inventarios (OBLIGATORIO) + +- [ ] DATABASE_INVENTORY.yml actualizado (si cambio DDL): + - [ ] Conteo de tablas correcto + - [ ] Conteo de enums correcto + - [ ] Conteo de funciones/triggers correcto + +- [ ] BACKEND_INVENTORY.yml actualizado (si cambio backend): + - [ ] Conteo de entities correcto + - [ ] Conteo de DTOs correcto + - [ ] Conteo de services/controllers correcto + +- [ ] FRONTEND_INVENTORY.yml actualizado (si cambio frontend): + - [ ] Conteo de components correcto + - [ ] Conteo de pages correcto + - [ ] Conteo de stores correcto + +- [ ] MASTER_INVENTORY.yml actualizado: + - [ ] Resumen consolidado correcto + - [ ] Fecha de actualizacion + +### Trazas (OBLIGATORIO) + +- [ ] TRAZA-TAREAS-DATABASE.md actualizado (si cambio DDL) +- [ ] TRAZA-TAREAS-BACKEND.md actualizado (si cambio backend) +- [ ] TRAZA-TAREAS-FRONTEND.md actualizado (si cambio frontend) +- [ ] TRAZA-CORRECCIONES.md actualizado (si fue fix) + +### Indice de Tareas (OBLIGATORIO) + +- [ ] _INDEX.yml actualizado con nueva entrada: + ```yaml + - id: TASK-YYYY-MM-DD-NNN + title: "Titulo" + date: "YYYY-MM-DD" + status: completed + path: "orchestration/tareas/TASK-.../" + ``` + +### SSOT (si aplica) + +- [ ] docs/_SSOT/TRACEABILITY-MASTER.yml actualizado (si nueva funcionalidad) +- [ ] docs/_SSOT/EPIC-INDEX.yml actualizado (si cambio estado de epica) +- [ ] docs/_SSOT/CODE-MAPPINGS.yml actualizado (si nuevos mappings) + +### Documentacion de Tarea + +- [ ] METADATA.yml de la tarea completado: + - [ ] Status: completed + - [ ] Completion: 100% + - [ ] Todas las fases marcadas como completed + - [ ] Metricas finales + +- [ ] SUBTASKS.yml de la tarea actualizado: + - [ ] Todas las subtareas marcadas como completed + - [ ] Summary actualizado + +### Lecciones Aprendidas + +- [ ] LESSONS-LEARNED.yml iniciado: + - [ ] Al menos "what_worked" o "what_didnt_work" completado + - [ ] Recomendaciones si aplica + +### Propagacion (si aplica) + +- [ ] Evaluada necesidad de propagacion a otros proyectos +- [ ] Si requiere propagacion: documentado en METADATA.yml + +--- + +## Criterios de Paso + +**PASA** si: +- Inventarios afectados actualizados +- _INDEX.yml actualizado +- METADATA.yml de tarea completado +- SUBTASKS.yml con summary correcto + +**NO PASA** si: +- Inventarios desactualizados +- Tarea no registrada en _INDEX.yml +- METADATA.yml incompleto + +--- + +## Siguiente Fase + +Si PASA: Continuar a **CHECKLIST-CIERRE.md** (Gate Final) +Si NO PASA: Completar documentacion faltante + +--- + +## Referencias + +- Trigger Inventarios: `orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md` +- Inventarios: `orchestration/inventarios/` +- SSOT: `docs/_SSOT/` diff --git a/orchestration/directivas/checklists/CHECKLIST-FASE-E.md b/orchestration/directivas/checklists/CHECKLIST-FASE-E.md new file mode 100644 index 000000000..00a57a824 --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-FASE-E.md @@ -0,0 +1,184 @@ +# CHECKLIST-FASE-E: Gate de Ejecucion + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-EJECUCION` + +## Proposito + +Validar ejecucion por checkpoints. Cada checkpoint es un gate de validacion. + +--- + +## Checkpoint CP1: Post-Database + +**Ejecutar despues de cambios en DDL** + +### Validaciones + +- [ ] DDL ejecuta sin errores de sintaxis +- [ ] `./scripts/recreate-database.sh` exitoso +- [ ] Tablas creadas/modificadas verificadas +- [ ] Enums definidos correctamente +- [ ] Foreign keys validas +- [ ] Indexes creados si aplica + +### Comandos de Validacion + +```bash +cd apps/database +./scripts/recreate-database.sh +# Verificar output sin errores +``` + +### Criterios de Paso CP1 + +- [ ] Sin errores de ejecucion DDL +- [ ] Estructura de BD consistente + +--- + +## Checkpoint CP2: Post-Backend + +**Ejecutar despues de cambios en Backend** + +### Validaciones + +- [ ] `npm run build` - PASA +- [ ] `npm run lint` - PASA (o warnings aceptables) +- [ ] `npm run test` - PASA (si existen tests) +- [ ] Entity alineada con DDL (campos, tipos) +- [ ] DTO definidos correctamente +- [ ] Service implementado +- [ ] Controller endpoints funcionan + +### Comandos de Validacion + +```bash +cd apps/backend +npm run build +npm run lint +npm run test +``` + +### Criterios de Paso CP2 + +- [ ] Build exitoso +- [ ] Lint pasa (< 5 warnings nuevos) +- [ ] Tests existentes pasan +- [ ] No hay errores de TypeScript + +--- + +## Checkpoint CP3: Post-Frontend + +**Ejecutar despues de cambios en Frontend** + +### Validaciones + +- [ ] `npm run build` - PASA +- [ ] `npm run typecheck` - PASA +- [ ] Componentes renderizan sin errores +- [ ] Integracion con API funciona +- [ ] Tipos alineados con backend DTOs + +### Comandos de Validacion + +```bash +cd apps/frontend +npm run build +npm run typecheck +``` + +### Criterios de Paso CP3 + +- [ ] Build exitoso +- [ ] Typecheck pasa +- [ ] Sin errores de consola en runtime + +--- + +## Checkpoint CP4: Coherencia Entre Capas + +**Ejecutar al final de ejecucion** + +### Validaciones + +- [ ] Entity alineada con DDL: + - [ ] Todos los campos de tabla tienen propiedad en entity + - [ ] Tipos TypeScript compatibles con tipos PostgreSQL + - [ ] Relaciones correctamente definidas + +- [ ] DTO alineado con Entity: + - [ ] DTOs exponen campos necesarios + - [ ] Transformaciones correctas + - [ ] Validaciones implementadas + +- [ ] Frontend consume correctamente: + - [ ] Endpoints correctos + - [ ] Tipos de respuesta alineados + - [ ] Manejo de errores + +### Matriz de Coherencia + +| DDL | Backend Entity | Backend DTO | Frontend | +|-----|----------------|-------------|----------| +| [ ] Tabla | [ ] Entity | [ ] DTO | [ ] API call | + +### Criterios de Paso CP4 + +- [ ] Sin gaps de coherencia criticos +- [ ] Documentacion de gaps menores si existen + +--- + +## Checklist General de Ejecucion + +### Durante Ejecucion + +- [ ] Seguir orden de SUBTASKS.yml +- [ ] Marcar subtareas completadas conforme avanzan +- [ ] No saltarse checkpoints +- [ ] Documentar decisiones tomadas + +### Manejo de Errores + +- [ ] Si falla un checkpoint: detener y resolver +- [ ] No avanzar con errores pendientes +- [ ] Documentar errores encontrados y resoluciones + +### Control de Cambios + +- [ ] Commits atomicos por subtarea +- [ ] Mensajes de commit descriptivos +- [ ] No mezclar cambios no relacionados + +--- + +## Criterios de Paso Fase E + +**PASA** si: +- CP1 pasa (si hubo cambios DB) +- CP2 pasa (si hubo cambios BE) +- CP3 pasa (si hubo cambios FE) +- CP4 pasa +- Todas las subtareas de E marcadas como completadas + +**NO PASA** si: +- Cualquier checkpoint falla +- Build/lint/test fallan +- Gaps de coherencia criticos + +--- + +## Siguiente Fase + +Si PASA: Continuar a **Fase D: Documentacion** +Si NO PASA: Resolver errores y re-ejecutar checkpoint + +--- + +## Referencias + +- Trigger Coherencia: `orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md` +- Inventarios: `orchestration/inventarios/` diff --git a/orchestration/directivas/checklists/CHECKLIST-FASE-P.md b/orchestration/directivas/checklists/CHECKLIST-FASE-P.md new file mode 100644 index 000000000..231f5e37f --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-FASE-P.md @@ -0,0 +1,75 @@ +# CHECKLIST-FASE-P: Gate de Plan + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-PLAN` + +## Proposito + +Validar que el plan de ejecucion esta completo y es viable. + +--- + +## Checklist + +### Desglose de Subtareas + +- [ ] SUBTASKS.yml completado con subtareas especificas +- [ ] Subtareas agrupadas por dominio (E.DB, E.BE, E.FE) +- [ ] Criterios de aceptacion definidos por subtarea +- [ ] Dependencias entre subtareas claras + +### Orden de Ejecucion + +- [ ] Secuencia de ejecucion definida +- [ ] Checkpoints identificados (CP1-CP4) +- [ ] Grupos que se pueden paralelizar identificados +- [ ] Bloqueantes considerados en secuencia + +### Validaciones Planeadas + +- [ ] Validaciones de build planificadas +- [ ] Validaciones de lint planificadas +- [ ] Validaciones de tests planificadas (si existen) +- [ ] Validacion de coherencia entre capas planificada + +### Recursos Necesarios + +- [ ] Archivos a crear identificados +- [ ] Archivos a modificar identificados +- [ ] Dependencias externas identificadas (si aplica) +- [ ] Acceso a sistemas necesarios confirmado + +### Estimacion + +- [ ] Complejidad estimada (low/medium/high) +- [ ] Esfuerzo estimado (horas/story points) +- [ ] Riesgos de tiempo considerados + +--- + +## Criterios de Paso + +**PASA** si: +- SUBTASKS.yml tiene al menos las fases E y D detalladas +- Orden de ejecucion es claro +- Checkpoints definidos + +**NO PASA** si: +- No hay desglose de subtareas +- Orden de ejecucion ambiguo +- Sin criterios de aceptacion + +--- + +## Siguiente Fase + +Si PASA: Continuar a **Fase V: Validacion Pre-Ejecucion** +Si NO PASA: Refinar plan + +--- + +## Referencias + +- SUBTASKS Template: `orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/SUBTASKS.yml` +- Principio CAPVED: `orchestration/directivas/principios/PRINCIPIO-CAPVED.md` diff --git a/orchestration/directivas/checklists/CHECKLIST-FASE-V.md b/orchestration/directivas/checklists/CHECKLIST-FASE-V.md new file mode 100644 index 000000000..cfe6a340a --- /dev/null +++ b/orchestration/directivas/checklists/CHECKLIST-FASE-V.md @@ -0,0 +1,81 @@ +# CHECKLIST-FASE-V: Gate de Validacion Pre-Ejecucion + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 +**Alias:** `@CHK-VALIDACION` + +## Proposito + +Gate de validacion antes de iniciar ejecucion. Verificar alineacion con requerimientos y viabilidad del plan. + +--- + +## Checklist + +### Alineacion con Requerimientos + +- [ ] Plan cubre todos los RF vinculados +- [ ] Plan cubre todos los criterios de las US +- [ ] No hay scope creep (alcance no autorizado) +- [ ] Cambios no contradicen documentacion existente + +### Viabilidad Tecnica + +- [ ] Codigo base esta en estado limpio (git status clean) +- [ ] Build actual pasa antes de iniciar +- [ ] No hay conflictos pendientes +- [ ] Ambiente de desarrollo funcional + +### Validacion de Dependencias + +- [ ] Tareas previas requeridas estan completadas +- [ ] Dependencias de codigo disponibles +- [ ] Si hay bloqueantes: resueltos o plan de resolucion + +### Coherencia Documental + +- [ ] Plan no contradice ADRs existentes +- [ ] Plan sigue estandares del proyecto +- [ ] Plan usa patrones establecidos + +### Aprobacion + +- [ ] Plan revisado (auto-revision o peer review) +- [ ] Riesgos aceptados +- [ ] Listo para ejecutar + +--- + +## Criterios de Paso + +**PASA** si: +- Plan alineado con RF/US +- Build actual pasa +- No hay bloqueantes activos +- Plan aprobado + +**NO PASA** si: +- Desalineacion con requerimientos +- Build actual falla +- Bloqueantes sin resolver +- Plan contradice documentacion + +--- + +## Siguiente Fase + +Si PASA: Continuar a **Fase E: Ejecucion** +Si NO PASA: Ajustar plan o resolver bloqueantes + +--- + +## Notas + +Este es el ultimo gate antes de modificar codigo. Asegurarse de que todo esta listo. + +--- + +## Referencias + +- ADRs: `docs/97-adr/` +- Estandares: `docs/40-estandares/` diff --git a/orchestration/directivas/checklists/README.md b/orchestration/directivas/checklists/README.md new file mode 100644 index 000000000..12a71a3c0 --- /dev/null +++ b/orchestration/directivas/checklists/README.md @@ -0,0 +1,100 @@ +# Checklists por Fase CAPVED + +**Version:** 1.0.0 +**Actualizado:** 2026-01-18 + +## Proposito + +Gates de validacion para cada fase del ciclo CAPVED. + +## Archivos + +| Checklist | Fase | Alias | Proposito | +|-----------|------|-------|-----------| +| CHECKLIST-FASE-C.md | Contexto | `@CHK-CONTEXTO` | Validar contextualizacion | +| CHECKLIST-FASE-A.md | Analisis | `@CHK-ANALISIS` | Validar analisis de impacto | +| CHECKLIST-FASE-P.md | Plan | `@CHK-PLAN` | Validar plan de ejecucion | +| CHECKLIST-FASE-V.md | Validacion | `@CHK-VALIDACION` | Gate pre-ejecucion | +| CHECKLIST-FASE-E.md | Ejecucion | `@CHK-EJECUCION` | Checkpoints CP1-CP4 | +| CHECKLIST-FASE-D.md | Documentacion | `@CHK-DOCUMENTACION` | Validar documentacion | +| CHECKLIST-CIERRE.md | Final | `@CHK-CIERRE`, `@DEF_CHK_POST` | Gate bloqueante final | + +## Flujo de Validacion + +``` +Tarea iniciada + | + v +[CHECKLIST-FASE-C] ── NO PASA ──> Completar items faltantes + | + PASA + | + v +[CHECKLIST-FASE-A] ── NO PASA ──> Completar analisis + | + PASA + | + v +[CHECKLIST-FASE-P] ── NO PASA ──> Refinar plan + | + PASA + | + v +[CHECKLIST-FASE-V] ── NO PASA ──> Resolver bloqueantes + | + PASA + | + v +[CHECKLIST-FASE-E] ── CP FALLA ──> Resolver y re-ejecutar + (CP1-CP4) + | + TODOS PASAN + | + v +[CHECKLIST-FASE-D] ── NO PASA ──> Completar documentacion + | + PASA + | + v +[CHECKLIST-CIERRE] ── NO PASA ──> Completar items + | + PASA + | + v +TAREA COMPLETADA +``` + +## Checkpoints de Ejecucion (Fase E) + +| Checkpoint | Cuando | Validaciones | +|------------|--------|--------------| +| CP1 | Post-Database | DDL, recreate-database | +| CP2 | Post-Backend | build, lint, test | +| CP3 | Post-Frontend | build, typecheck | +| CP4 | Final | Coherencia entre capas | + +## Uso + +### Durante ejecucion de tarea + +1. Antes de pasar a siguiente fase, ejecutar checklist correspondiente +2. Si no pasa, resolver items faltantes +3. Solo avanzar cuando todos los items pasen + +### Al finalizar tarea + +1. Ejecutar CHECKLIST-CIERRE.md completo +2. **BLOQUEANTE**: No marcar tarea como completada sin pasar +3. Documentar cualquier excepcion con justificacion + +## Integracion con Templates + +Los checklists estan referenciados en: +- `METADATA.yml` - Campo `phases.{fase}.checklist` +- `SUBTASKS.yml` - Dentro de cada fase + +## Referencias + +- Template de tarea: `orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/` +- Triggers: `orchestration/directivas/triggers/` +- Principio CAPVED: `orchestration/directivas/principios/PRINCIPIO-CAPVED.md` diff --git a/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/LESSONS-LEARNED.yml b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/LESSONS-LEARNED.yml new file mode 100644 index 000000000..a9e45c6a3 --- /dev/null +++ b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/LESSONS-LEARNED.yml @@ -0,0 +1,184 @@ +# LESSONS-LEARNED.yml - Lecciones Aprendidas de la Tarea +# Version: 1.0.0 +# Actualizado: 2026-01-18 +# +# Proposito: Documentar aprendizajes para mejorar futuras tareas + +# ============================================================================= +# METADATA +# ============================================================================= + +metadata: + task_id: "TASK-YYYY-MM-DD-NNN" + task_title: "Titulo de la tarea" + completed_date: "YYYY-MM-DD" + author: "Agente" + +# ============================================================================= +# RESUMEN EJECUTIVO +# ============================================================================= + +summary: + outcome: "success" # success | partial | failed + key_achievement: "Descripcion breve del logro principal" + main_challenge: "Descripcion breve del desafio principal" + time_deviation: "+2h" # vs estimado (ej: +2h, -1h, on-time) + +# ============================================================================= +# QUE FUNCIONO BIEN +# ============================================================================= + +what_worked: + - id: WW-001 + category: "process" # process | technical | communication | tooling + description: "Descripcion de lo que funciono bien" + impact: "high" # high | medium | low + replicable: true + details: | + Contexto adicional sobre por que funciono + y como replicarlo en futuras tareas. + + - id: WW-002 + category: "technical" + description: "Descripcion de solucion tecnica efectiva" + impact: "medium" + replicable: true + code_example: | + // Ejemplo de codigo si aplica + const solution = ... + +# ============================================================================= +# QUE NO FUNCIONO / PROBLEMAS +# ============================================================================= + +what_didnt_work: + - id: WD-001 + category: "process" + description: "Descripcion del problema encontrado" + impact: "high" + root_cause: "Causa raiz del problema" + resolution: "Como se resolvio o mitigó" + prevention: "Como prevenir en el futuro" + + - id: WD-002 + category: "technical" + description: "Problema tecnico encontrado" + impact: "medium" + root_cause: "Causa raiz" + resolution: "Solucion aplicada" + prevention: "Medida preventiva" + related_docs: + - "Link a ADR o documentacion relacionada" + +# ============================================================================= +# SORPRESAS / DESCUBRIMIENTOS +# ============================================================================= + +surprises: + - id: SU-001 + type: "positive" # positive | negative | neutral + description: "Algo inesperado que se descubrio" + impact: "medium" + action_taken: "Que se hizo al respecto" + follow_up: "Acciones futuras si aplica" + +# ============================================================================= +# RECOMENDACIONES PARA FUTURAS TAREAS +# ============================================================================= + +recommendations: + immediate: + - id: REC-I-001 + description: "Accion inmediata recomendada" + priority: "high" + owner: "Quien debe ejecutar" + + short_term: + - id: REC-S-001 + description: "Mejora para proximas tareas similares" + priority: "medium" + estimated_effort: "1h" + + long_term: + - id: REC-L-001 + description: "Mejora sistemica para el proyecto" + priority: "low" + requires_approval: true + +# ============================================================================= +# ACTUALIZACIONES A PROCESOS/DOCS +# ============================================================================= + +process_updates: + triggers: + - file: "orchestration/directivas/triggers/TRIGGER-XXX.md" + action: "update" # create | update | deprecate + description: "Actualizacion sugerida al trigger" + + checklists: + - file: "orchestration/directivas/checklists/CHECKLIST-XXX.md" + action: "update" + description: "Item a agregar al checklist" + + templates: + - file: "orchestration/templates/TEMPLATE-XXX.md" + action: "update" + description: "Mejora al template" + +# ============================================================================= +# METRICAS DE LA TAREA +# ============================================================================= + +task_metrics: + time: + estimated: "Xh" + actual: "Yh" + variance: "+/-Zh" + + scope: + planned_items: 10 + completed_items: 10 + added_items: 2 + removed_items: 0 + + quality: + bugs_found: 0 + rework_required: false + first_time_right: true + + complexity: + estimated: "medium" # low | medium | high + actual: "high" + reason_for_variance: "Razon si cambio" + +# ============================================================================= +# TAGS PARA BUSQUEDA +# ============================================================================= + +tags: + domains: [database, backend, frontend] + topics: [performance, security, refactoring] + technologies: [typescript, postgresql, react] + patterns: [repository, factory, observer] + +# ============================================================================= +# PROPAGACION +# ============================================================================= + +propagation: + should_propagate: true + target_index: "workspace-v2/orchestration/retrospectivas/LECCIONES-INDEX.yml" + propagated: false + propagated_date: null + +# ============================================================================= +# REFERENCIAS +# ============================================================================= + +references: + metadata: "./METADATA.yml" + subtasks: "./SUBTASKS.yml" + related_tasks: + - "TASK-YYYY-MM-DD-XXX: Tarea relacionada" + external_docs: + - "Link a documentacion externa relevante" diff --git a/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/METADATA.yml b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/METADATA.yml new file mode 100644 index 000000000..bab359e2f --- /dev/null +++ b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/METADATA.yml @@ -0,0 +1,230 @@ +# METADATA.yml - Template Unificado de Tarea +# Version: 2.0.0 +# Actualizado: 2026-01-18 + +# ============================================================================= +# IDENTIFICACION +# ============================================================================= + +task: + id: "TASK-YYYY-MM-DD-NNN" + title: "Titulo descriptivo de la tarea" + created: "YYYY-MM-DD" + updated: "YYYY-MM-DD" + +# ============================================================================= +# CLASIFICACION +# ============================================================================= + +classification: + type: "feature" # feature | bug | refactor | audit | migration | documentation + priority: "P1" # P0 (critico) | P1 (alto) | P2 (medio) | P3 (bajo) + mode: "FULL" # FULL | QUICK | ANALYSIS | PROPAGATION + epic: "EAI-003" # Epica relacionada (si aplica) + sprint: "Sprint-XX" # Sprint actual (si aplica) + +# ============================================================================= +# ESTADO +# ============================================================================= + +status: + current: "pending" # pending | in_progress | blocked | completed + blocked_by: null # ID de tarea/issue bloqueante + completion: 0% + last_phase: null # C | A | P | V | E | D + +# ============================================================================= +# DOMINIOS AFECTADOS +# ============================================================================= + +domains: + - name: "database" + affected: true + details: "Descripcion de cambios en BD" + + - name: "backend" + affected: true + details: "Descripcion de cambios en backend" + + - name: "frontend" + affected: false + details: null + + - name: "documentation" + affected: true + details: "Actualizacion de inventarios" + +# ============================================================================= +# REQUERIMIENTOS Y DEPENDENCIAS +# ============================================================================= + +requirements: + functional: + - "RF-XXX-001: Descripcion" + technical: + - "ET-XXX-001: Descripcion" + user_stories: + - "US-XXX-001: Como usuario quiero..." + +dependencies: + tasks_required: + - "TASK-YYYY-MM-DD-NNN: Tarea previa necesaria" + tasks_blocked: + - "TASK-YYYY-MM-DD-NNN: Tarea que espera esta" + epics_related: + - "EAI-003: Gamificacion" + +# ============================================================================= +# FASES CAPVED +# ============================================================================= + +phases: + contexto: + status: "pending" # pending | in_progress | completed | skipped + started: null + completed: null + file: "01-CONTEXTO.md" + checklist: "CHECKLIST-FASE-C.md" + + analisis: + status: "pending" + started: null + completed: null + file: "02-ANALISIS.md" + checklist: "CHECKLIST-FASE-A.md" + + plan: + status: "pending" + started: null + completed: null + file: "03-PLAN.md" + checklist: "CHECKLIST-FASE-P.md" + + validacion: + status: "pending" + started: null + completed: null + file: "04-VALIDACION.md" + checklist: "CHECKLIST-FASE-V.md" + + ejecucion: + status: "pending" + started: null + completed: null + file: "05-EJECUCION.md" + checklist: "CHECKLIST-FASE-E.md" + checkpoints: + CP1_database: "pending" + CP2_backend: "pending" + CP3_frontend: "pending" + CP4_coherencia: "pending" + + documentacion: + status: "pending" + started: null + completed: null + file: "06-DOCUMENTACION.md" + checklist: "CHECKLIST-FASE-D.md" + +# ============================================================================= +# SUBTAREAS +# ============================================================================= + +subtasks_file: "SUBTASKS.yml" + +subtasks_summary: + total: 0 + completed: 0 + in_progress: 0 + pending: 0 + blocked: 0 + +# ============================================================================= +# ENTREGABLES +# ============================================================================= + +deliverables: + code: + - path: "apps/backend/src/..." + type: "new" # new | modified | deleted + description: "Descripcion del cambio" + + documentation: + - path: "docs/..." + type: "modified" + description: "Actualizacion de documentacion" + + reports: + - name: "REPORT-XXX.md" + description: "Reporte generado" + +# ============================================================================= +# VALIDACIONES +# ============================================================================= + +validations: + build: + backend: null # pass | fail | pending + frontend: null + database: null + + lint: + backend: null + frontend: null + + tests: + backend: null + frontend: null + + coherence: + ddl_backend: null + backend_frontend: null + +# ============================================================================= +# METRICAS +# ============================================================================= + +metrics: + time: + estimated_hours: null + actual_hours: null + changes: + files_created: 0 + files_modified: 0 + files_deleted: 0 + lines_added: 0 + lines_removed: 0 + issues: + found: 0 + fixed: 0 + deferred: 0 + +# ============================================================================= +# AGENTE +# ============================================================================= + +agent: + id: "agente-principal" + session: "session-id" + workspace: "workspace-v2" + +# ============================================================================= +# HISTORIAL +# ============================================================================= + +changelog: + - date: "YYYY-MM-DD" + author: "Agente" + action: "created" + details: "Tarea creada" + +# ============================================================================= +# REFERENCIAS +# ============================================================================= + +references: + subtasks: "./SUBTASKS.yml" + lessons: "./LESSONS-LEARNED.yml" + ssot: "docs/_SSOT/" + epic_manifest: "docs/XX-fase-*/EPIC-XXX/EPIC-MANIFEST.yml" + checklist_cierre: "orchestration/directivas/checklists/CHECKLIST-CIERRE.md" diff --git a/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/README.md b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/README.md new file mode 100644 index 000000000..b2c8a85fa --- /dev/null +++ b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/README.md @@ -0,0 +1,129 @@ +# TASK-TEMPLATE-UNIFIED + +**Version:** 2.0.0 +**Actualizado:** 2026-01-18 + +## Proposito + +Template unificado para tareas que integra: +- Metadata estructurada (METADATA.yml) +- Sistema recursivo de subtareas N niveles (SUBTASKS.yml) +- Registro de lecciones aprendidas (LESSONS-LEARNED.yml) + +## Archivos + +| Archivo | Proposito | +|---------|-----------| +| `METADATA.yml` | Identificacion, clasificacion, estado, fases CAPVED | +| `SUBTASKS.yml` | Desglose recursivo hasta 5 niveles | +| `LESSONS-LEARNED.yml` | Documentacion de aprendizajes post-tarea | +| `README.md` | Este archivo | + +## Como Usar + +### 1. Crear nueva tarea + +```bash +# Crear carpeta con ID de tarea +mkdir orchestration/tareas/TASK-2026-01-18-001 + +# Copiar template +cp -r orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/* orchestration/tareas/TASK-2026-01-18-001/ +``` + +### 2. Actualizar METADATA.yml + +```yaml +task: + id: "TASK-2026-01-18-001" + title: "Titulo real de la tarea" + created: "2026-01-18" +``` + +### 3. Definir subtareas en SUBTASKS.yml + +Adaptar las subtareas segun los dominios afectados: +- Eliminar grupos no necesarios (ej: E.FE si no hay cambios frontend) +- Agregar subtareas especificas +- Definir criterios de aceptacion + +### 4. Ejecutar tarea siguiendo CAPVED + +1. **C** - Contexto: Vincular con RF/ET/US +2. **A** - Analisis: Mapear dependencias e impacto +3. **P** - Plan: Detallar subtareas en SUBTASKS.yml +4. **V** - Validacion: Gate de aprobacion +5. **E** - Ejecucion: Implementar por checkpoints (CP1-CP4) +6. **D** - Documentacion: Actualizar inventarios, trazas, lecciones + +### 5. Completar LESSONS-LEARNED.yml + +Al finalizar la tarea: +- Documentar que funciono bien +- Documentar problemas y resoluciones +- Agregar recomendaciones + +## Estructura de Niveles (SUBTASKS.yml) + +``` +NIVEL 1: FASE +├── C (Contexto) +├── A (Analisis) +├── P (Plan) +├── V (Validacion) +├── E (Ejecucion) ← NIVEL 2: GRUPO +│ ├── E.DB (Database) +│ ├── E.BE (Backend) ← NIVEL 3: SUBTAREA +│ │ ├── E.BE.01 +│ │ │ ├── E.BE.01.AC1 ← NIVEL 4: CRITERIO +│ │ │ │ └── AC1.1 ← NIVEL 5: SUB-CRITERIO +│ │ │ └── E.BE.01.AC2 +│ │ └── E.BE.02 +│ ├── E.FE (Frontend) +│ └── E.COH (Coherencia) +└── D (Documentacion) +``` + +## Checkpoints de Ejecucion + +| Checkpoint | Validaciones | +|------------|--------------| +| CP1: Post-Database | DDL ejecuta, recreate-database.sh exitoso | +| CP2: Post-Backend | npm run build, lint, test - PASAN | +| CP3: Post-Frontend | npm run build, typecheck - PASAN | +| CP4: Coherencia | Entity↔DDL, DTO↔Entity, FE↔BE alineados | + +## Estados de Subtareas + +| Estado | Descripcion | +|--------|-------------| +| `pending` | No iniciado | +| `in_progress` | En ejecucion | +| `completed` | Terminado exitosamente | +| `blocked` | Bloqueado por dependencia | +| `skipped` | Omitido (documentar razon) | + +## Integracion con Sistema + +### Actualizar _INDEX.yml al completar + +```yaml +tasks: + - id: TASK-2026-01-18-001 + title: "Titulo de la tarea" + date: "2026-01-18" + status: completed + path: "orchestration/tareas/TASK-2026-01-18-001/" +``` + +### Propagar lecciones al workspace + +Si `propagation.should_propagate: true` en LESSONS-LEARNED.yml: +1. Copiar entrada relevante a `workspace-v2/orchestration/retrospectivas/LECCIONES-INDEX.yml` +2. Marcar `propagated: true` + +## Referencias + +- SSOT: `docs/_SSOT/` +- Checklists CAPVED: `orchestration/directivas/checklists/` +- Template anterior: `workspace-v2/orchestration/tareas/_templates/TASK-TEMPLATE/` diff --git a/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/SUBTASKS.yml b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/SUBTASKS.yml new file mode 100644 index 000000000..50b25b9b9 --- /dev/null +++ b/orchestration/tareas/_templates/TASK-TEMPLATE-UNIFIED/SUBTASKS.yml @@ -0,0 +1,353 @@ +# SUBTASKS.yml - Sistema Recursivo de Subtareas (N Niveles) +# Version: 1.0.0 +# Actualizado: 2026-01-18 +# +# ESTRUCTURA DE NIVELES: +# Nivel 1: FASE (C, A, P, V, E, D) +# Nivel 2: GRUPO/DOMINIO (E.DB, E.BE, E.FE) +# Nivel 3: SUBTAREA +# Nivel 4: CRITERIO DE ACEPTACION +# Nivel 5: SUB-CRITERIO (si necesario) + +# ============================================================================= +# METADATA +# ============================================================================= + +metadata: + task_id: "TASK-YYYY-MM-DD-NNN" + version: "1.0.0" + max_depth: 5 + total_items: 0 + completed_items: 0 + +# ============================================================================= +# RESUMEN POR FASE +# ============================================================================= + +summary: + C: + total: 0 + completed: 0 + percentage: 0% + A: + total: 0 + completed: 0 + percentage: 0% + P: + total: 0 + completed: 0 + percentage: 0% + V: + total: 0 + completed: 0 + percentage: 0% + E: + total: 0 + completed: 0 + percentage: 0% + D: + total: 0 + completed: 0 + percentage: 0% + +# ============================================================================= +# SUBTAREAS - NIVEL 1: FASES +# ============================================================================= + +subtasks: + # ------------------------------------------------------------------------- + # FASE C: CONTEXTO + # ------------------------------------------------------------------------- + - id: "C" + tipo: "fase" + nombre: "Contexto" + status: "pending" # pending | in_progress | completed | blocked | skipped + descripcion: "Clasificar y vincular tarea con objetivos del proyecto" + children: + - id: "C.01" + tipo: "subtarea" + titulo: "Identificar requerimientos relacionados" + status: "pending" + acceptance_criteria: + - id: "C.01.AC1" + descripcion: "RF/ET/US vinculados en METADATA.yml" + status: "pending" + + - id: "C.02" + tipo: "subtarea" + titulo: "Verificar catalogo de funcionalidades" + status: "pending" + acceptance_criteria: + - id: "C.02.AC1" + descripcion: "No hay duplicacion con funcionalidades existentes" + status: "pending" + + # ------------------------------------------------------------------------- + # FASE A: ANALISIS + # ------------------------------------------------------------------------- + - id: "A" + tipo: "fase" + nombre: "Analisis" + status: "pending" + descripcion: "Mapear impacto, dependencias y riesgos" + children: + - id: "A.01" + tipo: "subtarea" + titulo: "Analizar dependencias de codigo" + status: "pending" + acceptance_criteria: + - id: "A.01.AC1" + descripcion: "Archivos dependientes identificados" + status: "pending" + - id: "A.01.AC2" + descripcion: "Impacto de cambios evaluado" + status: "pending" + + - id: "A.02" + tipo: "subtarea" + titulo: "Identificar riesgos" + status: "pending" + acceptance_criteria: + - id: "A.02.AC1" + descripcion: "Riesgos documentados con mitigacion" + status: "pending" + + # ------------------------------------------------------------------------- + # FASE P: PLAN + # ------------------------------------------------------------------------- + - id: "P" + tipo: "fase" + nombre: "Plan" + status: "pending" + descripcion: "Desglosar subtareas por dominio" + children: + - id: "P.01" + tipo: "subtarea" + titulo: "Definir subtareas de ejecucion" + status: "pending" + acceptance_criteria: + - id: "P.01.AC1" + descripcion: "Subtareas E.DB, E.BE, E.FE definidas" + status: "pending" + + - id: "P.02" + tipo: "subtarea" + titulo: "Establecer orden de ejecucion" + status: "pending" + acceptance_criteria: + - id: "P.02.AC1" + descripcion: "Dependencias entre subtareas claras" + status: "pending" + + # ------------------------------------------------------------------------- + # FASE V: VALIDACION (Gate) + # ------------------------------------------------------------------------- + - id: "V" + tipo: "fase" + nombre: "Validacion Pre-Ejecucion" + status: "pending" + descripcion: "Gate de validacion antes de ejecutar" + children: + - id: "V.01" + tipo: "subtarea" + titulo: "Validar alineacion con requerimientos" + status: "pending" + acceptance_criteria: + - id: "V.01.AC1" + descripcion: "Plan alineado con RF/ET" + status: "pending" + + - id: "V.02" + tipo: "subtarea" + titulo: "Aprobar plan de ejecucion" + status: "pending" + acceptance_criteria: + - id: "V.02.AC1" + descripcion: "Plan aprobado para continuar" + status: "pending" + + # ------------------------------------------------------------------------- + # FASE E: EJECUCION (Nivel 2: Grupos por Dominio) + # ------------------------------------------------------------------------- + - id: "E" + tipo: "fase" + nombre: "Ejecucion" + status: "pending" + descripcion: "Implementar cambios por dominio" + children: + # --- GRUPO E.DB: Database --- + - id: "E.DB" + tipo: "grupo" + dominio: "database" + nombre: "Cambios en Base de Datos" + status: "pending" + checkpoint: "CP1" + children: + - id: "E.DB.01" + tipo: "subtarea" + titulo: "[Descripcion de cambio DDL]" + status: "pending" + dependencias: [] + acceptance_criteria: + - id: "E.DB.01.AC1" + descripcion: "DDL ejecuta sin errores" + status: "pending" + - id: "E.DB.01.AC2" + descripcion: "recreate-database.sh exitoso" + status: "pending" + + # --- GRUPO E.BE: Backend --- + - id: "E.BE" + tipo: "grupo" + dominio: "backend" + nombre: "Cambios en Backend" + status: "pending" + checkpoint: "CP2" + dependencias: ["E.DB"] # Depende de que BD este lista + children: + - id: "E.BE.01" + tipo: "subtarea" + titulo: "[Descripcion de cambio backend]" + status: "pending" + acceptance_criteria: + - id: "E.BE.01.AC1" + descripcion: "Entity creada/modificada" + status: "pending" + - id: "E.BE.01.AC2" + descripcion: "npm run build - PASA" + status: "pending" + - id: "E.BE.01.AC3" + descripcion: "npm run lint - PASA" + status: "pending" + - id: "E.BE.01.AC4" + descripcion: "npm run test - PASA" + status: "pending" + + # --- GRUPO E.FE: Frontend --- + - id: "E.FE" + tipo: "grupo" + dominio: "frontend" + nombre: "Cambios en Frontend" + status: "pending" + checkpoint: "CP3" + dependencias: ["E.BE"] # Depende de que backend este listo + children: + - id: "E.FE.01" + tipo: "subtarea" + titulo: "[Descripcion de cambio frontend]" + status: "pending" + acceptance_criteria: + - id: "E.FE.01.AC1" + descripcion: "Componente creado/modificado" + status: "pending" + - id: "E.FE.01.AC2" + descripcion: "npm run build - PASA" + status: "pending" + - id: "E.FE.01.AC3" + descripcion: "npm run typecheck - PASA" + status: "pending" + + # --- GRUPO E.COH: Coherencia --- + - id: "E.COH" + tipo: "grupo" + dominio: "coherencia" + nombre: "Validacion de Coherencia" + status: "pending" + checkpoint: "CP4" + dependencias: ["E.DB", "E.BE", "E.FE"] + children: + - id: "E.COH.01" + tipo: "subtarea" + titulo: "Verificar coherencia entre capas" + status: "pending" + acceptance_criteria: + - id: "E.COH.01.AC1" + descripcion: "Entity alineada con DDL" + status: "pending" + - id: "E.COH.01.AC2" + descripcion: "DTO alineado con Entity" + status: "pending" + - id: "E.COH.01.AC3" + descripcion: "Frontend consume endpoints correctos" + status: "pending" + + # ------------------------------------------------------------------------- + # FASE D: DOCUMENTACION + # ------------------------------------------------------------------------- + - id: "D" + tipo: "fase" + nombre: "Documentacion" + status: "pending" + descripcion: "Actualizar inventarios, trazas y propagar" + children: + - id: "D.01" + tipo: "subtarea" + titulo: "Actualizar inventarios" + status: "pending" + acceptance_criteria: + - id: "D.01.AC1" + descripcion: "DATABASE_INVENTORY.yml actualizado (si aplica)" + status: "pending" + - id: "D.01.AC2" + descripcion: "BACKEND_INVENTORY.yml actualizado (si aplica)" + status: "pending" + - id: "D.01.AC3" + descripcion: "FRONTEND_INVENTORY.yml actualizado (si aplica)" + status: "pending" + - id: "D.01.AC4" + descripcion: "MASTER_INVENTORY.yml actualizado" + status: "pending" + + - id: "D.02" + tipo: "subtarea" + titulo: "Actualizar trazas" + status: "pending" + acceptance_criteria: + - id: "D.02.AC1" + descripcion: "TRAZA-TAREAS-*.md actualizado" + status: "pending" + - id: "D.02.AC2" + descripcion: "_INDEX.yml actualizado" + status: "pending" + + - id: "D.03" + tipo: "subtarea" + titulo: "Registrar lecciones aprendidas" + status: "pending" + acceptance_criteria: + - id: "D.03.AC1" + descripcion: "LESSONS-LEARNED.yml completado" + status: "pending" + + - id: "D.04" + tipo: "subtarea" + titulo: "Ejecutar CHECKLIST-CIERRE.md" + status: "pending" + acceptance_criteria: + - id: "D.04.AC1" + descripcion: "Todos los items del checklist pasan" + status: "pending" + +# ============================================================================= +# INSTRUCCIONES DE USO +# ============================================================================= +# +# 1. Copiar este archivo a la carpeta de la tarea +# 2. Actualizar metadata.task_id +# 3. Completar/eliminar subtareas segun necesidad +# 4. Para agregar niveles adicionales, usar children recursivamente +# 5. Actualizar status conforme avanza la ejecucion +# 6. Mantener summary actualizado +# +# ESTADOS: +# pending - No iniciado +# in_progress - En ejecucion +# completed - Terminado exitosamente +# blocked - Bloqueado por dependencia +# skipped - Omitido (documentar razon) +# +# CHECKPOINTS (en Fase E): +# CP1 - Post-Database: DDL ejecuta, recreate exitoso +# CP2 - Post-Backend: build, lint, test pasan +# CP3 - Post-Frontend: build, typecheck pasan +# CP4 - Coherencia: Capas alineadas