[GOBERNANZA] feat: Propagar gobernanza completa a clinica-veterinaria
- Crear _definitions/ con protocolos, validaciones y checklists - Configurar rol CONSUMER con tipo_herencia SPECIALIZES - Definir modulos propios: mascotas, vacunacion, hospitalizacion - Crear docs/_SSOT/ con estructura de trazabilidad Herencia: erp-core -> erp-clinicas -> clinica-veterinaria Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
3bb417fef3
commit
faeb932c89
34
docs/_SSOT/README.md
Normal file
34
docs/_SSOT/README.md
Normal file
@ -0,0 +1,34 @@
|
||||
# Single Source of Truth (SSOT) - CLINICA-VETERINARIA
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Fecha:** 2026-01-18
|
||||
**Proyecto:** clinica-veterinaria
|
||||
**Sistema:** SIMCO v4.0.0
|
||||
|
||||
---
|
||||
|
||||
## Herencia
|
||||
|
||||
```
|
||||
template-saas (PROVIDER)
|
||||
↓
|
||||
erp-core (INTERMEDIATE)
|
||||
↓
|
||||
erp-clinicas (INTERMEDIATE)
|
||||
↓
|
||||
clinica-veterinaria (SPECIALIZES) ← ESTE PROYECTO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Archivos SSOT
|
||||
|
||||
| Archivo | Descripcion | Estado |
|
||||
|---------|-------------|--------|
|
||||
| EPIC-INDEX.yml | Indice de epicas | PENDIENTE |
|
||||
| TRACEABILITY-MASTER.yml | Trazabilidad maestra | PENDIENTE |
|
||||
|
||||
---
|
||||
|
||||
**Creado:** 2026-01-18
|
||||
**Mantenido por:** @CLINICA_VETERINARIA_ORCHESTRATOR
|
||||
82
orchestration/_definitions/_INDEX.yml
Normal file
82
orchestration/_definitions/_INDEX.yml
Normal file
@ -0,0 +1,82 @@
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
# ÍNDICE DE DEFINICIONES CANÓNICAS - CLINICA-VETERINARIA
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
version: "1.0.0"
|
||||
created: "2026-01-18"
|
||||
updated: "2026-01-18"
|
||||
maintained_by: "@WS_ORCHESTRATOR"
|
||||
propagated_from: "erp-clinicas/orchestration/_definitions/"
|
||||
role: "CONSUMER" # Especialización de erp-clinicas
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────────
|
||||
# PROTOCOLOS
|
||||
# ─────────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
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
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────────
|
||||
# CONFIGURACIÓN DE HERENCIA (SPECIALIZES)
|
||||
# ─────────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
consumer_config:
|
||||
role: "CONSUMER"
|
||||
inherits_from: "erp-clinicas" # Especialización de erp-clinicas
|
||||
inherits_version: "1.0.0"
|
||||
tipo_herencia: "SPECIALIZES"
|
||||
modulos_heredados:
|
||||
- pacientes (adaptado a mascotas)
|
||||
- citas
|
||||
- expedientes (adaptado)
|
||||
modulos_propios:
|
||||
- mascotas
|
||||
- vacunacion
|
||||
- hospitalizacion
|
||||
propagates_to: []
|
||||
sync_strategy: "AUTO"
|
||||
vertical: "clinica-veterinaria"
|
||||
nota: "Clínica veterinaria especializada - hereda de erp-clinicas"
|
||||
@ -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
|
||||
244
orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md
Normal file
244
orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md
Normal file
@ -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
|
||||
107
orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md
Normal file
107
orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md
Normal file
@ -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
|
||||
149
orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md
Normal file
149
orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md
Normal file
@ -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
|
||||
347
orchestration/_definitions/protocols/CAPVED-CYCLE.md
Normal file
347
orchestration/_definitions/protocols/CAPVED-CYCLE.md
Normal file
@ -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
|
||||
245
orchestration/_definitions/protocols/CCA-PROTOCOL.md
Normal file
245
orchestration/_definitions/protocols/CCA-PROTOCOL.md
Normal file
@ -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
|
||||
81
orchestration/_definitions/validations/VALIDATION-BACKEND.md
Normal file
81
orchestration/_definitions/validations/VALIDATION-BACKEND.md
Normal file
@ -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
|
||||
89
orchestration/_definitions/validations/VALIDATION-DDL.md
Normal file
89
orchestration/_definitions/validations/VALIDATION-DDL.md
Normal file
@ -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
|
||||
@ -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
|
||||
Loading…
Reference in New Issue
Block a user