rckrdmrd/clinica-dental
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[CLINICA-DENTAL] chore: Update orchestration and inventories

Browse Source 
- Updated database submodule
- Added SIMCO directivas
- Updated inventory files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
rckrdmrd 2026-01-20 04:37:06 -06:00
parent 0f828f924c
commit dc8c5dcc52
23 changed files with 5868 additions and 433 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
database

@ -1 +1 @@
Subproject commit 8c61a7e449105e019484720eafdcdeddae46c0c4 Subproject commit 0330700dd9ebee0204f14fe713887d6bb3a6642b

287
orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md Normal file
View File

@ -0,0 +1,287 @@
# PRINCIPIO: ANTI-DUPLICACIÓN
**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA
**Aplica a:** TODOS los agentes sin excepción
---
## DECLARACIÓN DEL PRINCIPIO
```
╔══════════════════════════════════════════════════════════════════════╗
║ ║
║ ANTES DE CREAR, VERIFICAR QUE NO EXISTE ║
║ ║
║ "Un duplicado creado es tiempo perdido y confusión garantizada." ║
║ "2 minutos de verificación ahorran horas de corrección." ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## REGLA DE ORO
```
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ NUNCA crear un objeto (tabla, entity, componente, etc.) │
│ sin antes verificar que NO existe algo igual o similar. │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## PROCESO DE VERIFICACIÓN
### Paso 0: Consultar Catálogo de Funcionalidades (NUEVO - OBLIGATORIO)
```bash
# 🆕 PRIMERO: Verificar si existe funcionalidad en catálogo global
grep -i "{funcionalidad}" @CATALOG_INDEX
# Funcionalidades comunes ya catalogadas:
# - auth (login, registro, JWT)
# - session-management (sesiones, dispositivos)
# - rate-limiting (throttle, 429)
# - notifications (email, push)
# - multi-tenancy (tenant, RLS)
# - feature-flags (toggles)
# - websocket (realtime)
# - payments (stripe)
```
**Si encuentra en @CATALOG:**
```
✅ USAR CÓDIGO DEL CATÁLOGO
1. Ir a @CATALOG/{funcionalidad}/
2. Leer README.md (descripción y trade-offs)
3. Seguir IMPLEMENTATION.md (pasos)
4. Copiar _reference/ (código base)
5. Adaptar configuración al proyecto
Ver: @REUTILIZAR (SIMCO-REUTILIZAR.md)
```
### Paso 1: Consultar Inventario del Proyecto
```bash
# Buscar en inventario maestro
grep -i "{nombre}" @INVENTORY
# Buscar en inventario específico
grep -i "{nombre}" @INV_DB # Para database
grep -i "{nombre}" @INV_BE # Para backend
grep -i "{nombre}" @INV_FE # Para frontend
```
### Paso 2: Buscar en Código
```bash
# Buscar archivos con nombre similar
find apps/ -name "*{nombre}*" -type f
# Buscar definiciones en código
grep -rn "CREATE TABLE.*{nombre}" apps/
grep -rn "class {Nombre}" apps/
grep -rn "export.*{Nombre}" apps/
```
### Paso 3: Evaluar Resultado
| Resultado | Acción |
|-----------|--------|
| Existe en @CATALOG | ✅ REUTILIZAR del catálogo (ver @REUTILIZAR) |
| No encontrado | ✅ Proceder a crear |
| Encontrado idéntico | 🛑 DETENER - No crear, usar existente |
| Encontrado similar | ⚠️ PREGUNTAR - ¿Modificar existente o crear diferente? |
---
## QUÉ VERIFICAR POR TIPO
### Database (DDL)
```bash
# Verificar tabla
grep -rn "CREATE TABLE.*{nombre}" @DDL_ROOT
grep -i "{nombre}" @INV_DB
# Verificar schema
grep -rn "CREATE SCHEMA.*{nombre}" @DDL_ROOT
# Verificar función
grep -rn "CREATE.*FUNCTION.*{nombre}" @DDL_ROOT
```
### Backend (NestJS)
```bash
# Verificar entity
find @BACKEND -name "*{nombre}*.entity.ts"
grep -rn "class {Nombre}Entity" @BACKEND
# Verificar service
find @BACKEND -name "*{nombre}*.service.ts"
grep -rn "class {Nombre}Service" @BACKEND
# Verificar controller
find @BACKEND -name "*{nombre}*.controller.ts"
```
### Frontend (React)
```bash
# Verificar componente
find @FRONTEND -name "*{Nombre}*.tsx"
grep -rn "export.*{Nombre}" @FRONTEND_ROOT
# Verificar hook
find @FRONTEND -name "use{Nombre}*.ts"
# Verificar type
grep -rn "interface {Nombre}\|type {Nombre}" @FRONTEND_ROOT
```
---
## SI ENCUENTRAS DUPLICADO
### Duplicado Exacto
```markdown
🛑 DETENER INMEDIATAMENTE
El objeto `{nombre}` YA EXISTE:
- **Ubicación:** {ruta}
- **Inventario:** {línea en inventario}
- **Estado:** {estado}
**Acción:** Usar el existente, NO crear nuevo.
**Si necesitas modificarlo:**
Ver @MODIFICAR (SIMCO-MODIFICAR.md)
```
### Objeto Similar
```markdown
⚠️ OBJETO SIMILAR ENCONTRADO
Encontré `{nombre_similar}` que podría ser lo mismo:
- **Ubicación:** {ruta}
- **Propósito:** {descripción}
**Preguntas a resolver:**
1. ¿Es el mismo objeto con diferente nombre?
2. ¿Debo modificar el existente?
3. ¿Son diferentes y debo crear con otro nombre?
ESPERAR CLARIFICACIÓN antes de proceder.
```
---
## CONSECUENCIAS DE DUPLICAR
```
❌ Confusión sobre cuál usar
→ Diferentes partes del código usan diferentes versiones
❌ Mantenimiento duplicado
→ Cambios deben hacerse en múltiples lugares
❌ Bugs por inconsistencia
→ Un objeto se actualiza, el duplicado no
❌ Inventarios incorrectos
→ Estado del proyecto confuso
❌ Tiempo perdido
→ Trabajo que hay que deshacer
```
---
## PREVENCIÓN PROACTIVA
### Al Planificar
```markdown
ANTES de diseñar nuevo objeto:
1. [ ] Busqué en inventarios
2. [ ] Busqué en código
3. [ ] Confirmé que no existe
```
### Al Crear
```markdown
DURANTE creación de objeto:
1. [ ] Nombre no colisiona con existente
2. [ ] Ubicación es única
3. [ ] Propósito no está cubierto por otro objeto
```
### Al Completar
```markdown
DESPUÉS de crear:
1. [ ] Actualicé inventario
2. [ ] No hay advertencias de duplicados
```
---
## CASOS ESPECIALES
### ¿Qué pasa si necesito algo PARECIDO pero diferente?
```markdown
Ejemplo: Existe `UserEntity`, necesito `AdminUserEntity`
Verificar:
1. ¿Es una extensión? → Heredar/extender existente
2. ¿Es un caso especial? → Agregar campo al existente
3. ¿Es realmente diferente? → Crear nuevo con nombre claro
Nombrar claramente:
- ❌ `User2Entity` (confuso)
- ✅ `AdminUserEntity` (claro y diferenciado)
```
### ¿Qué pasa si el existente está mal?
```markdown
Si el objeto existente tiene problemas:
1. Documentar los problemas
2. Decidir: ¿Corregir existente o reemplazar?
3. Si reemplazar: eliminar viejo completamente
4. NUNCA tener ambos coexistiendo
```
---
## CHECKLIST RÁPIDO
```
Antes de crear CUALQUIER objeto:
[ ] 🆕 Busqué funcionalidad en @CATALOG_INDEX (PRIMERO)
[ ] Busqué "{nombre}" en @INVENTORY
[ ] Busqué archivos con find
[ ] Busqué definiciones con grep
[ ] Confirmé que NO existe en catálogo NI en proyecto
[ ] Si existe en catálogo, seguí @REUTILIZAR
[ ] Si existe similar, pregunté qué hacer
```
---
## REFERENCIAS SIMCO
- **@CATALOG** - Catálogo de funcionalidades reutilizables (CONSULTAR PRIMERO)
- **@REUTILIZAR** - Proceso para reutilizar del catálogo
- **@CREAR** - Proceso completo de creación (incluye verificación)
- **@BUSCAR** - Estrategias de búsqueda
- **@DOCUMENTAR** - Actualización de inventarios
---
**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.**
---
**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental

384
orchestration/directivas/principios/PRINCIPIO-CAPVED.md Normal file
View File

@ -0,0 +1,384 @@
---
tipo: ssot-normativo
nivel: 3-completo
es_ssot: true
versiones_derivadas:
- docs/30-directivas/CICLO-CAPVED.md (nivel 1 - resumen usuario)
- orchestration/_definitions/protocols/CAPVED-CYCLE.md (nivel 2 - tecnico)
actualizado: 2026-01-16
---
# PRINCIPIO: CAPVED - Ciclo de Vida de Tareas
**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA - **SSOT**
**Aplica a:** TODOS los agentes sin excepción
**Alias:** @CAPVED
---
## DECLARACIÓN DEL PRINCIPIO
```
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ CAPVED: Contexto → Análisis → Planeación → Validación → Ejecución → Doc ║
║ ║
║ "Toda tarea que modifica código o documentación DEBE pasar por ║
║ el ciclo completo CAPVED antes de considerarse Done." ║
║ ║
║ "Si aparece trabajo fuera del alcance original, se genera HU nueva." ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
```
---
## QUÉ ES CAPVED
CAPVED es un **ciclo de vida obligatorio** para toda Historia de Usuario (HU) o tarea técnica que involucre modificación de código o documentación. Garantiza:
1. **Trazabilidad completa**: Desde el origen hasta la implementación
2. **Análisis de impacto**: Antes de tocar código
3. **Validación de coherencia**: Plan vs Análisis
4. **Generación controlada**: HUs derivadas para descubrimientos
5. **Documentación actualizada**: Como criterio de Done
---
## LAS 6 FASES DE CAPVED
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ C - CONTEXTO │
│ • Vincular HU a proyecto/módulo/epic │
│ • Clasificar tipo: feature | fix | refactor | spike | doc-only │
│ • Registrar origen: plan-original | descubrimiento | incidencia │
│ • Cargar documentos SIMCO relevantes │
├─────────────────────────────────────────────────────────────────────────────┤
│ ↓ │
├─────────────────────────────────────────────────────────────────────────────┤
│ A - ANÁLISIS │
│ • Comportamiento deseado (perspectiva de negocio) │
│ • Restricciones: seguridad, performance, UX │
│ • Objetos impactados: BD, Backend, Frontend, otros proyectos │
│ • Dependencias con otras HUs (bloquea/bloqueada por) │
│ • Riesgos identificados │
│ → SALIDA: Lista de objetos + dependencias + riesgos │
├─────────────────────────────────────────────────────────────────────────────┤
│ ↓ │
├─────────────────────────────────────────────────────────────────────────────┤
│ P - PLANEACIÓN │
│ • Desglose en subtareas por dominio (BD, BE, FE, Docs) │
│ • Orden de ejecución y dependencias │
│ • Criterios de aceptación por subtarea │
│ • Plan de pruebas: unitarias, integración, regresión │
│ • Asignación de agentes/subagentes │
│ → SALIDA: Plan de ejecución con subtareas asignadas │
├─────────────────────────────────────────────────────────────────────────────┤
│ ↓ │
├─────────────────────────────────────────────────────────────────────────────┤
│ V - VALIDACIÓN (⚠️ NO DELEGAR - EJECUTAR DIRECTAMENTE) │
│ • ¿Todo lo detectado en A tiene acción concreta en P? │
│ • ¿Hay dependencias ocultas sin atender? │
│ • ¿Criterios de aceptación cubren los riesgos? │
│ • ¿Hay scope creep? → Registrar y crear HU derivada │
│ → GATE: Solo pasa a Ejecución si todo cuadra │
├─────────────────────────────────────────────────────────────────────────────┤
│ ↓ │
├─────────────────────────────────────────────────────────────────────────────┤
│ E - EJECUCIÓN │
│ • Actualizar docs/ del proyecto PRIMERO │
│ • Ejecutar subtareas en orden establecido │
│ • Cada subtarea: código + notas + validación (build/lint) │
│ • Registrar progreso y desviaciones │
│ → USAR: SIMCO correspondientes (CREAR, MODIFICAR, DDL, etc.) │
├─────────────────────────────────────────────────────────────────────────────┤
│ ↓ │
├─────────────────────────────────────────────────────────────────────────────┤
│ D - DOCUMENTACIÓN CONTINUA │
│ • Actualizar diagramas y modelos de dominio │
│ • Actualizar especificaciones técnicas (BD, APIs, contratos) │
│ • Crear/actualizar ADRs si hubo decisiones arquitectónicas │
│ • Actualizar inventarios (DATABASE, BACKEND, FRONTEND) │
│ • Actualizar trazas de tareas │
│ • Registrar HUs derivadas (si se generaron) │
│ • Registrar lecciones aprendidas │
│ → GATE: HU NO está Done si documentación no está actualizada │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## CUÁNDO APLICA CAPVED
### APLICA A (Obligatorio):
```yaml
Tareas_que_DEBEN_seguir_CAPVED:
- Nuevas features (cualquier tamaño)
- Bug fixes que modifican código
- Refactorizaciones
- Cambios en estructura de BD
- Nuevos endpoints de API
- Nuevos componentes de UI
- Cambios en lógica de negocio
- Integraciones con sistemas externos
- Cualquier tarea que genere commit
```
### NO APLICA A (Excepciones):
```yaml
Tareas_exentas_de_CAPVED_completo:
- Corrección de typos en código (solo E+D)
- Actualización de dependencias menores (solo E+D)
- Tareas puramente exploratorias (solo lectura)
- Consultas de información
- Spikes de investigación sin implementación
NOTA: Incluso las excepciones DEBEN documentar en trazas
```
---
## INTEGRACIÓN CON SIMCO
CAPVED es el **ciclo de vida**, SIMCO son las **operaciones**:
```
CAPVED SIMCO
─────── ─────
C - Contexto → SIMCO-INICIALIZACION.md (CCA)
A - Análisis → SIMCO-BUSCAR.md + docs/
P - Planeación → TEMPLATE-PLAN.md
V - Validación → Checklist CAPVED (este documento)
E - Ejecución → SIMCO-CREAR/MODIFICAR/DDL/BACKEND/FRONTEND
D - Documentación → SIMCO-DOCUMENTAR.md + inventarios + trazas
```
### Orden de Lectura para Agentes:
```yaml
1. SIMCO-INICIALIZACION.md # Bootstrap con CCA
2. PRINCIPIO-CAPVED.md # Este documento (ciclo obligatorio)
3. PRINCIPIO-DOC-PRIMERO.md # Documentación antes de código
4. PRINCIPIO-ANTI-DUPLICACION.md # Verificar antes de crear
5. PRINCIPIO-VALIDACION-OBLIGATORIA.md # Build/lint obligatorios
6. SIMCO-TAREA.md # Proceso detallado CAPVED
7. SIMCO específicos según operación
```
---
## GENERACIÓN DE HUs DERIVADAS
### Cuándo Generar HU Nueva:
```yaml
Generar_HU_derivada_cuando:
# Durante Análisis (A)
- Se detecta bug estructural no relacionado al objetivo
- Se identifica deuda técnica que bloquea
- Se descubre dependencia no documentada
# Durante Validación (V)
- Hay trabajo detectado fuera del alcance original
- Se requiere refactor previo no planificado
- Se identifica mejora de UX no solicitada
# Durante Ejecución (E)
- Se encuentra código legacy que debe corregirse
- Se descubre inconsistencia en otra parte del sistema
- Se identifica oportunidad de optimización
```
### Proceso de Generación:
```markdown
1. DETECTAR: Identificar que algo está fuera del alcance
2. REGISTRAR: Documentar en la sección "HUs Derivadas" de la HU actual
3. CREAR: Generar archivo de HU con prefijo DERIVED-{HU-ORIGEN}-{N}
4. VINCULAR: Referenciar la HU origen en la nueva HU
5. PRIORIZAR: Marcar como pendiente para siguiente planificación
6. CONTINUAR: Seguir con la HU original sin desviarse
```
### Template de Registro:
```yaml
HUs_Derivadas:
- id: "DERIVED-HU-001-001"
origen: "HU-001"
tipo: "bug | feature | refactor | deuda-tecnica"
descripcion: "Descripción breve de lo detectado"
detectado_en_fase: "A | V | E"
prioridad_sugerida: "P0 | P1 | P2 | P3"
notas: "Contexto adicional relevante"
```
---
## CHECKLIST RÁPIDO CAPVED
### Antes de Iniciar (C):
```
[ ] HU vinculada a proyecto/módulo/epic
[ ] Tipo clasificado (feature/fix/refactor/spike/doc-only)
[ ] Origen registrado (plan/descubrimiento/incidencia)
[ ] Documentos SIMCO relevantes identificados
```
### Antes de Planificar (A completado):
```
[ ] Comportamiento de negocio entendido
[ ] Objetos impactados listados (todas las capas)
[ ] Dependencias identificadas
[ ] Riesgos documentados
```
### Antes de Ejecutar (P+V completados):
```
[ ] Subtareas definidas por dominio
[ ] Orden de ejecución establecido
[ ] Criterios de aceptación definidos
[ ] Plan vs Análisis validado (todo cubierto)
[ ] Scope creep registrado (si existe)
[ ] HUs derivadas creadas (si aplica)
```
### Durante Ejecución (E):
```
[ ] docs/ actualizado PRIMERO
[ ] Subtareas ejecutadas en orden
[ ] Build/lint pasa por subtarea
[ ] Progreso registrado
```
### Antes de Cerrar (D):
```
[ ] Diagramas/modelos actualizados
[ ] Specs técnicas actualizadas
[ ] ADRs creados (si decisión arquitectónica)
[ ] Inventarios actualizados
[ ] Trazas actualizadas
[ ] HUs derivadas vinculadas
[ ] Lecciones aprendidas registradas
```
### GATE DE CIERRE (OBLIGATORIO - @DEF_CHK_POST)
> **ANTES de declarar una HU/tarea como DONE, ejecutar @DEF_CHK_POST**
```markdown
## Checklist de Cierre Obligatorio
### Gobernanza (BLOQUEANTE)
[ ] Carpeta de tarea existe: orchestration/tareas/TASK-{ID}/
[ ] METADATA.yml completo con fases C, E, D
[ ] _INDEX.yml de tareas actualizado
### Validaciones Técnicas
[ ] Build pasa (backend y/o frontend)
[ ] Lint pasa
[ ] Tests pasan (si existen)
### Coherencia Entre Capas
[ ] DDL ↔ Backend verificado
[ ] Backend ↔ Frontend verificado (si aplica)
### Inventarios
[ ] DATABASE_INVENTORY.yml (si cambió BD)
[ ] BACKEND_INVENTORY.yml (si cambió BE)
[ ] FRONTEND_INVENTORY.yml (si cambió FE)
[ ] MASTER_INVENTORY.yml actualizado
### Trazas
[ ] Traza de tarea correspondiente actualizada
[ ] PROXIMA-ACCION.md actualizado
### Propagación
[ ] Evaluado si aplica a otros proyectos
```
**SI FALLA CUALQUIER ITEM BLOQUEANTE:** HU permanece EN PROGRESO.
**REFERENCIA:** `@TRIGGER_CIERRE` - orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md
---
## CONSECUENCIAS DE IGNORAR CAPVED
```
❌ Saltar Contexto (C)
→ HU sin trazabilidad, trabajo desconectado del plan
❌ Saltar Análisis (A)
→ Impacto no previsto, bugs en otras partes del sistema
❌ Saltar Planeación (P)
→ Ejecución caótica, trabajo rehecho, tiempo perdido
❌ Saltar Validación (V)
→ Scope creep no controlado, trabajo infinito
❌ Saltar Documentación (D)
→ Sistema diverge de docs/, confusión futura, onboarding difícil
```
---
## LECCIONES APRENDIDAS
### Registro Obligatorio:
Al cerrar cada HU, registrar:
```yaml
Lecciones_Aprendidas:
que_funciono_bien:
- "Descripción de práctica exitosa"
que_se_puede_mejorar:
- "Descripción de área de mejora"
para_futuras_HUs_similares:
- "Recomendación específica para HUs del mismo tipo"
```
### Ubicación:
- En el archivo de la HU (sección final)
- Consolidar mensualmente en `orchestration/retrospectivas/`
---
## REFERENCIAS SIMCO
| Fase CAPVED | SIMCO Relacionados |
|-------------|-------------------|
| C - Contexto | `SIMCO-INICIALIZACION.md`, `CONTEXTO-PROYECTO.md` |
| A - Análisis | `SIMCO-BUSCAR.md`, `TEMPLATE-ANALISIS.md` |
| P - Planeación | `TEMPLATE-PLAN.md`, `SIMCO-DELEGACION.md` |
| V - Validación | `TEMPLATE-VALIDACION.md` |
| E - Ejecución | `SIMCO-CREAR.md`, `SIMCO-MODIFICAR.md`, `SIMCO-DDL.md`, etc. |
| D - Documentación | `SIMCO-DOCUMENTAR.md`, inventarios, trazas |
---
## ALIAS
```yaml
@CAPVED: core/orchestration/directivas/principios/PRINCIPIO-CAPVED.md
@TAREA: core/orchestration/directivas/simco/SIMCO-TAREA.md
@TPL_CAPVED: core/orchestration/templates/TEMPLATE-TAREA-CAPVED.md
```
---
**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.**
---
**Versión:** 1.0.0 | **Sistema:** SIMCO + CAPVED | **Tipo:** Principio Fundamental

190
orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md Normal file
View File

@ -0,0 +1,190 @@
# PRINCIPIO: DOCUMENTACIÓN PRIMERO
**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA
**Aplica a:** TODOS los agentes sin excepción
---
## DECLARACIÓN DEL PRINCIPIO
```
╔══════════════════════════════════════════════════════════════════════╗
║ ║
║ DOCUMENTACIÓN PRIMERO, IMPLEMENTACIÓN DESPUÉS ║
║ ║
║ "Si no está documentado, no existe." ║
║ "Si contradice la documentación, está mal." ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## REGLA EN 3 PASOS
```
PASO 1: ANTES DE IMPLEMENTAR
─────────────────────────────
Consultar docs/ para entender:
- ¿Qué dice la documentación sobre esto?
- ¿Hay especificaciones o diseños?
- ¿Hay ADRs relacionados?
PASO 2: SI HAY CAMBIO DE DISEÑO
─────────────────────────────
Actualizar docs/ PRIMERO:
- Documentar el nuevo diseño
- Crear ADR si es decisión arquitectónica
- Actualizar especificaciones
PASO 3: IMPLEMENTAR
─────────────────────────────
Solo entonces escribir código:
- Seguir lo documentado
- Referenciar docs/ en comentarios si aplica
```
---
## FLUJO VISUAL
```
┌─────────────────────┐
│ TAREA NUEVA │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ ¿Consulté docs/? │──── NO ────► CONSULTAR DOCS/ PRIMERO
└──────────┬──────────┘
│ SÍ
▼
┌─────────────────────┐
│ ¿Hay contradicción? │──── SÍ ────► ACTUALIZAR DOCS/ PRIMERO
└──────────┬──────────┘
│ NO
▼
┌─────────────────────┐
│ ¿Falta documentar? │──── SÍ ────► DOCUMENTAR PRIMERO
└──────────┬──────────┘
│ NO
▼
┌─────────────────────┐
│ IMPLEMENTAR │
└─────────────────────┘
```
---
## DOCUMENTACIÓN A CONSULTAR
### Antes de CUALQUIER tarea:
```yaml
Obligatorio:
- docs/00-vision-general/ # Visión y alcance
- docs/95-guias-desarrollo/ # Estándares y convenciones
- docs/97-adr/ # Decisiones arquitectónicas
Si aplica:
- docs/01-fase-*/ # Especificaciones por fase
- docs/modulos/{modulo}/ # Especificaciones del módulo
- orchestration/inventarios/ # Estado actual del proyecto
```
### Para cada tipo de tarea:
```yaml
Database:
- @GUIAS/database/ (si existe)
- @ADR (decisiones de BD)
Backend:
- @GUIAS_BE/DTO-CONVENTIONS.md
- @GUIAS_BE/API-CONVENTIONS.md
- @ADR
Frontend:
- @GUIAS_FE/TYPES-CONVENTIONS.md
- @GUIAS_FE/COMPONENT-PATTERNS.md
- @ADR
```
---
## CUÁNDO ACTUALIZAR DOCS/ PRIMERO
| Situación | Acción |
|-----------|--------|
| Nueva feature no documentada | Documentar diseño antes de implementar |
| Cambio de arquitectura | Crear ADR antes de implementar |
| Contradicción docs/ vs realidad | Actualizar docs/ (si realidad es correcta) |
| Nueva convención | Documentar en guías antes de usar |
| Nuevo módulo/schema | Documentar estructura antes de crear |
---
## CUÁNDO NO APLICA
```yaml
Excepciones (no requiere actualizar docs/ primero):
- Bug fixes menores (solo corrección, no cambio de diseño)
- Refactors internos (misma funcionalidad)
- Actualizaciones de dependencias
- Corrección de typos en código
PERO siempre aplica:
- Consultar docs/ para entender el contexto
- Documentar en traza lo realizado
- Actualizar inventarios si hay cambios estructurales
```
---
## CONSECUENCIAS DE IGNORAR ESTE PRINCIPIO
```
❌ Código que contradice documentación
→ Confusión, bugs, deuda técnica
❌ Features no documentadas
→ Nadie sabe qué hace ni por qué
❌ Implementar sin consultar docs/
→ Duplicados, inconsistencias, trabajo rehecho
❌ Cambiar arquitectura sin ADR
→ Decisiones perdidas, errores repetidos
```
---
## CHECKLIST RÁPIDO
```
Antes de escribir código:
[ ] Consulté docs/ relevantes
[ ] No hay contradicción con lo documentado
[ ] Si hay cambio de diseño, actualicé docs/ primero
Al terminar:
[ ] Código sigue lo documentado
[ ] Actualicé inventarios
[ ] Documenté en traza
```
---
## REFERENCIAS SIMCO
- **@DOCUMENTAR** - Cómo documentar correctamente
- **@VALIDAR** - Validación de coherencia docs/código
- **@BUSCAR** - Cómo encontrar documentación
---
**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.**
---
**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental

292
orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md Normal file
View File

@ -0,0 +1,292 @@
# PRINCIPIO: ECONOMÍA DE TOKENS
**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Aplica a:** Todos los agentes
**Prioridad:** OBLIGATORIA para evitar errores de context overflow
---
## RESUMEN EJECUTIVO
> **Los agentes tienen límites de tokens. Excederlos = fallo de tarea.**
> Planificar con economía de tokens = tareas exitosas.
> Tareas grandes sin desglose = error garantizado.
---
## LÍMITES CRÍTICOS
```yaml
CONTEXTO_MAXIMO:
entrada: ~200,000 tokens # Lo que el agente puede "ver"
salida: ~8,000 tokens # Lo que puede generar por respuesta
recomendado_carga: <50,000 tokens # Para dejar espacio de trabajo
ARCHIVO_INDIVIDUAL:
maximo_recomendado: 500 líneas (~2,000 tokens)
ideal: 200-300 líneas (~1,000 tokens)
alerta: >400 líneas → considerar división
PROMPT_DELEGACION:
maximo: 3,000 tokens (~750 líneas de prompt)
recomendado: 1,500 tokens (~375 líneas)
minimo_efectivo: 500 tokens (~125 líneas)
```
---
## REGLAS DE ECONOMÍA
### Regla 1: Cargar Solo Lo Necesario
```yaml
MAL:
- Cargar TODOS los archivos del proyecto
- Leer archivos completos cuando solo necesitas una sección
- Incluir documentación extendida en prompts de delegación
BIEN:
- Cargar SOLO archivos relevantes para la tarea actual
- Usar SIMCO-QUICK-REFERENCE.md en lugar de _INDEX.md completo
- Referencias a archivos en vez de copiar contenido
```
### Regla 2: Desglosar Tareas Grandes
```yaml
TAREA_GRANDE (>2000 tokens de output esperado):
- Dividir en subtareas independientes
- Cada subtarea = máximo 1 archivo o 1 función
- Secuenciar: crear → validar → siguiente
EJEMPLO_MALO:
"Crear el módulo completo de usuarios con entity, service,
controller, DTOs, tests, y documentación"
# Esto generará >8000 tokens de salida = ERROR
EJEMPLO_BUENO:
ST-001: Crear UserEntity alineada con DDL
ST-002: Crear CreateUserDto y UpdateUserDto
ST-003: Crear UserService con CRUD básico
ST-004: Crear UserController con endpoints
ST-005: Ejecutar build + lint
# Cada una <2000 tokens = ÉXITO
```
### Regla 3: Prompts de Delegación Concisos
```yaml
INCLUIR:
- Contexto mínimo necesario (nivel, variables críticas)
- Tarea específica (1 cosa)
- Criterios de aceptación (checklist corto)
- 1-2 archivos de referencia máximo
NO INCLUIR:
- Historia completa del proyecto
- Documentación extendida
- Múltiples opciones/alternativas
- Código de ejemplo extenso (>50 líneas)
```
---
## ESTRATEGIAS DE DESGLOSE
### Por Capa (Vertical)
```yaml
# En lugar de: "Crear feature de notificaciones"
# Desglosar en:
ST-001_DATABASE:
tarea: "Crear tabla notifications.notifications"
output_esperado: ~300 tokens (1 archivo DDL)
ST-002_BACKEND_ENTITY:
tarea: "Crear NotificationEntity"
output_esperado: ~200 tokens (1 archivo)
ST-003_BACKEND_DTO:
tarea: "Crear DTOs de Notification"
output_esperado: ~300 tokens (2 archivos pequeños)
ST-004_BACKEND_SERVICE:
tarea: "Crear NotificationService con CRUD"
output_esperado: ~400 tokens (1 archivo)
ST-005_BACKEND_CONTROLLER:
tarea: "Crear NotificationController con endpoints"
output_esperado: ~350 tokens (1 archivo)
ST-006_VALIDACION:
tarea: "Ejecutar build + lint backend"
output_esperado: ~100 tokens (comandos)
```
### Por Funcionalidad (Horizontal)
```yaml
# En lugar de: "Implementar autenticación"
# Desglosar en:
ST-001: Verificar @CATALOG (¿existe auth?)
ST-002: Si existe → usar SIMCO-REUTILIZAR
ST-003: Si no existe → crear esquema auth (DDL)
ST-004: Crear AuthModule básico (register/login)
ST-005: Crear JWT strategy
ST-006: Crear guards
ST-007: Integrar en app.module
ST-008: Validar build + lint
```
---
## ESTIMACIÓN DE TOKENS
### Fórmula Rápida
```
tokens ≈ caracteres / 4
tokens ≈ palabras * 1.3
tokens ≈ líneas * 10 (código promedio)
```
### Tabla de Referencia
| Tipo de Archivo | Líneas Típicas | Tokens Estimados |
|-----------------|----------------|------------------|
| Entity simple | 30-50 | 300-500 |
| Entity con relaciones | 80-120 | 800-1200 |
| DTO | 20-40 | 200-400 |
| Service CRUD | 100-150 | 1000-1500 |
| Controller REST | 80-120 | 800-1200 |
| Tabla DDL | 30-60 | 300-600 |
| Componente React simple | 50-80 | 500-800 |
| Componente React complejo | 150-250 | 1500-2500 |
| Hook | 30-60 | 300-600 |
---
## DETECCIÓN DE PROBLEMAS
### Señales de Alerta
```yaml
ANTES_DE_EJECUTAR:
- [ ] ¿La tarea pide crear >3 archivos? → Desglosar
- [ ] ¿El prompt de delegación >1500 tokens? → Reducir
- [ ] ¿Se pide "módulo completo"? → Desglosar por componente
- [ ] ¿Se incluye código de referencia >50 líneas? → Usar referencia a archivo
DURANTE_EJECUCION:
- [ ] ¿Respuesta truncada? → Tarea muy grande
- [ ] ¿Error de context? → Demasiados archivos cargados
- [ ] ¿Alucinaciones? → Contexto insuficiente o confuso
```
### Acciones Correctivas
```yaml
SI_RESPUESTA_TRUNCADA:
1. Dividir tarea en 2-3 subtareas
2. Re-ejecutar cada subtarea por separado
3. Validar entre subtareas
SI_ERROR_CONTEXT:
1. Descargar archivos no esenciales
2. Usar SIMCO-QUICK-REFERENCE en lugar de _INDEX completo
3. Referencias en lugar de contenido inline
SI_ALUCINACIONES:
1. Verificar que archivos de referencia se cargaron
2. Incluir más contexto específico (menos genérico)
3. Ser más explícito en criterios de aceptación
```
---
## TEMPLATE DE DELEGACIÓN OPTIMIZADO
```yaml
# PROMPT OPTIMIZADO (~800 tokens)
## SUBAGENTE: {Tipo}
Nivel: {nivel} | Proyecto: {proyecto} | Ruta: {orchestration_path}
## TAREA ÚNICA
{Descripción en 1-2 oraciones}
## ESPECIFICACIÓN
{Solo lo necesario, máximo 10 líneas}
## REFERENCIA
- Archivo: `{ruta exacta}` (copiar patrón de líneas X-Y)
## CRITERIOS (máximo 5)
- [ ] {criterio 1}
- [ ] {criterio 2}
- [ ] {criterio 3}
## VALIDACIÓN
```bash
{1-2 comandos}
```
## ENTREGABLES
1. {archivo a crear/modificar}
```
---
## INTEGRACIÓN CON CAPVED
### Fase P (Planeación) - Verificar Tokens
```yaml
ANTES_DE_APROBAR_PLAN:
- [ ] Cada subtarea genera <2000 tokens de output
- [ ] Cada prompt de delegación <1500 tokens
- [ ] No hay subtareas que pidan "módulo completo"
- [ ] Subtareas son independientes (pueden fallar sin afectar otras)
```
### Fase E (Ejecución) - Monitorear
```yaml
DURANTE_EJECUCION:
- Si subtarea falla por tokens → subdividir más
- Si contexto insuficiente → cargar archivo específico
- Si respuesta truncada → dividir y reintentar
```
---
## MÉTRICAS DE ÉXITO
```yaml
TAREA_BIEN_DESGLOSADA:
- 0 errores de token overflow
- 0 respuestas truncadas
- Cada subtarea completa en 1 iteración
- Build pasa después de cada subtarea
DELEGACION_OPTIMA:
- Prompt <1500 tokens
- Respuesta completa sin truncar
- Criterios verificables cumplidos
- Sin re-trabajo por malentendidos
```
---
## REFERENCIAS
- **Referencia rápida:** `SIMCO-QUICK-REFERENCE.md`
- **Delegación:** `SIMCO-DELEGACION.md`
- **Desglose de tareas:** `SIMCO-TAREA.md`
---
**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental

361
orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md Normal file
View File

@ -0,0 +1,361 @@
# PRINCIPIO: NO ASUMIR
**Version:** 1.0.0
**Fecha:** 2025-12-12
**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA
**Aplica a:** TODOS los agentes sin excepcion
---
## DECLARACION DEL PRINCIPIO
```
╔══════════════════════════════════════════════════════════════════════╗
║ ║
║ "Si no esta documentado, NO asumir. PREGUNTAR." ║
║ ║
║ Nunca implementar basado en suposiciones. ║
║ Nunca inventar requisitos. ║
║ Nunca tomar decisiones de negocio sin autorizacion. ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## REGLA INQUEBRANTABLE
```
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ PROHIBIDO: │
│ - Asumir valores/comportamientos no documentados │
│ - Inventar requisitos o especificaciones │
│ - Tomar decisiones de negocio sin consultar │
│ - Implementar "lo que parece logico" sin confirmacion │
│ - Interpretar ambiguedad a favor de una opcion │
│ - Completar huecos de documentacion con suposiciones │
│ │
│ OBLIGATORIO: │
│ - Detener trabajo cuando falta informacion critica │
│ - Documentar la pregunta claramente │
│ - Escalar al Product Owner │
│ - Esperar respuesta antes de continuar │
│ - Documentar la decision antes de implementar │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## POR QUE ESTE PRINCIPIO
```yaml
problema:
- Implementaciones basadas en suposiciones causan retrabajo
- Asunciones incorrectas generan bugs de negocio
- Decisiones no autorizadas crean deuda tecnica
- Interpretaciones personales divergen del objetivo real
consecuencias_de_asumir:
- Codigo que no cumple requisitos reales
- Retrabajo costoso cuando se descubre la asuncion incorrecta
- Perdida de confianza del cliente/PO
- Documentacion desalineada con implementacion
- Bugs dificiles de rastrear (parecen funcionar pero no son correctos)
beneficios_de_preguntar:
- Implementacion correcta desde el inicio
- Documentacion completa y precisa
- Menos retrabajo
- Mayor confianza del equipo
- Decisiones respaldadas por autoridad correcta
```
---
## CUANDO APLICA ESTE PRINCIPIO
### Casos que REQUIEREN Escalamiento
```yaml
informacion_faltante:
- Tabla mencionada sin definicion de columnas
- Endpoint sin especificacion de payload
- Pagina sin definicion de componentes
- Regla de negocio incompleta
- Valores de enum no especificados
- Validaciones no documentadas
- Comportamiento de error no definido
- Limites/umbrales no especificados
ambiguedad:
- Requisito interpretable de multiples formas
- Contradiccion entre documentos
- Alcance no claramente definido
- Criterios de aceptacion vagos
- Casos edge no cubiertos
decisiones_de_negocio:
- Cambio que afecta UX
- Modificacion de flujos existentes
- Nuevas restricciones
- Priorizacion entre alternativas
- Trade-offs con impacto en usuario
```
### Casos que NO Requieren Escalamiento
```yaml
decisiones_tecnicas_puras:
- Nombre de variable interna
- Estructura de codigo (si no afecta API)
- Optimizaciones de rendimiento
- Refactorizaciones internas
→ Consultar Architecture-Analyst si hay duda
implementacion_clara:
- Documentacion existe y es clara
- No hay ambiguedad
- Comportamiento esta especificado
→ Proceder con implementacion
estandares_definidos:
- Nomenclatura definida en directivas
- Patrones definidos en SIMCO
- Convenciones del proyecto
→ Seguir lo establecido
```
---
## COMO APLICAR ESTE PRINCIPIO
### Paso 1: Buscar Exhaustivamente
```yaml
ANTES_de_escalar:
buscar_en:
- docs/01-requerimientos/
- docs/02-especificaciones-tecnicas/
- docs/97-adr/
- orchestration/inventarios/
- Codigo existente relacionado
- Historial de trazas
tiempo_minimo: "10-15 minutos de busqueda activa"
```
### Paso 2: Si No se Encuentra, Documentar
```markdown
## INFORMACION NO ENCONTRADA
**Busqueda realizada:**
- [X] docs/01-requerimientos/ - No encontrado
- [X] docs/02-especificaciones-tecnicas/ - Mencionado pero incompleto
- [X] ADRs - No hay ADR relacionado
- [X] Inventarios - N/A
**Conclusion:** Informacion no disponible, requiere escalamiento
```
### Paso 3: Escalar Correctamente
```markdown
## CONSULTA AL PRODUCT OWNER
**Fecha:** {fecha}
**Agente:** {agente}
**Tarea:** [{ID}] {titulo}
### Contexto
{que estoy haciendo}
### Lo que encontre
{informacion parcial disponible}
### Lo que falta / es ambiguo
{descripcion clara del gap}
### Pregunta especifica
{pregunta concreta}
### Opciones (si las identifique)
1. {opcion A}
2. {opcion B}
### Impacto
{que pasa si no se resuelve}
```
### Paso 4: Esperar y Documentar Respuesta
```yaml
MIENTRAS_espero:
- NO implementar esa parte
- Continuar con otras tareas si es posible
- Marcar tarea como BLOQUEADA si es critico
CUANDO_recibo_respuesta:
- Documentar la decision
- Actualizar documentacion correspondiente
- Crear ADR si es decision significativa
- Continuar implementacion
```
---
## FLUJO DE DECISION
```
┌─────────────────────────────────────┐
│ Encontrar informacion faltante │
│ o ambiguedad │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Buscar exhaustivamente en docs │
│ (10-15 minutos minimo) │
└──────────────┬──────────────────────┘
│
▼
┌──────┴──────┐
│ Encontrado? │
└──────┬──────┘
│
┌────────┴────────┐
│ SI │ NO
▼ ▼
┌───────────┐ ┌─────────────────────┐
│ Proceder │ │ DETENER │
│ con │ │ Documentar pregunta │
│ implement │ │ Escalar al PO │
└───────────┘ └──────────┬──────────┘
│
▼
┌─────────────────────┐
│ ESPERAR respuesta │
│ (NO asumir) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Documentar decision │
│ Continuar │
└─────────────────────┘
```
---
## EJEMPLOS
### Ejemplo CORRECTO
```yaml
situacion: "DDL menciona campo 'status' pero no especifica valores"
proceso_correcto:
1. Buscar en docs/: No encontrado
2. Buscar en specs: Solo dice "tiene status"
3. Buscar en ADRs: No hay ADR
4. Conclusion: Escalar
5. Documentar: "Cuales son los valores validos de status?"
6. Esperar respuesta
7. PO responde: "['draft', 'active', 'completed']"
8. Documentar decision
9. Implementar con valores correctos
```
### Ejemplo INCORRECTO
```yaml
situacion: "DDL menciona campo 'status' pero no especifica valores"
proceso_incorrecto:
1. "Parece que deberian ser 'pending', 'done'"
2. Implementar con esos valores
3. PO revisa y dice: "No, son 'draft', 'active', 'completed'"
4. Retrabajo: migration, seed update, tests, backend, frontend
5. Tiempo perdido: 2-4 horas
```
---
## CONSECUENCIAS DE IGNORAR
```yaml
ignorar_este_principio:
retrabajo:
- Implementacion incorrecta debe rehacerse
- Tests basados en asuncion incorrecta
- Documentacion desalineada
bugs_de_negocio:
- Funcionalidad no cumple expectativas
- Comportamiento inesperado para usuarios
- Datos incorrectos en sistema
deuda_tecnica:
- Codigo parche sobre asuncion incorrecta
- Inconsistencias acumuladas
- Complejidad innecesaria
perdida_de_confianza:
- PO pierde confianza en implementaciones
- Mas revision necesaria
- Ciclos de feedback mas largos
```
---
## CHECKLIST RAPIDO
```
Antes de implementar algo no 100% claro:
[ ] Busque en documentacion? (10-15 min minimo)
[ ] Revise specs, ADRs, inventarios?
[ ] Sigue sin estar claro?
[ ] Documente la pregunta?
[ ] Escale al PO?
[ ] Espere respuesta?
[ ] Documente la decision?
[ ] Actualice documentacion correspondiente?
Solo entonces: Proceder con implementacion
```
---
## RELACION CON OTROS PRINCIPIOS
```yaml
PRINCIPIO-DOC-PRIMERO:
- Leer docs antes de implementar
- Si docs estan incompletos -> NO-ASUMIR aplica
PRINCIPIO-CAPVED:
- Fase A (Analisis): Identificar informacion faltante
- Fase V (Validacion): NO aprobar sin informacion completa
PRINCIPIO-VALIDACION-OBLIGATORIA:
- Validar que implementacion coincide con decision documentada
```
---
## REFERENCIAS SIMCO
- **@ESCALAMIENTO** - Proceso completo de escalamiento
- **@DOC_PRIMERO** - Consultar documentacion primero
- **@TAREA** - Ciclo de vida de tareas
---
**Este principio es OBLIGATORIO y NO puede ser ignorado por ningun agente.**
---
**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental

248
orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md Normal file
View File

@ -0,0 +1,248 @@
# PRINCIPIO: VALIDACIÓN OBLIGATORIA
**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA
**Aplica a:** TODOS los agentes sin excepción
---
## DECLARACIÓN DEL PRINCIPIO
```
╔══════════════════════════════════════════════════════════════════════╗
║ ║
║ BUILD PASA + LINT PASA = REQUISITO MÍNIMO ║
║ ║
║ "Código que no compila NO está terminado." ║
║ "Tarea con errores NO está completada." ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## REGLA INQUEBRANTABLE
```
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ NINGUNA tarea se marca como COMPLETADA si: │
│ │
│ • Build falla │
│ • Lint tiene errores críticos │
│ • Carga limpia falla (para DDL) │
│ • Tests fallan (si existen) │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## VALIDACIONES POR CAPA
### Database (DDL)
```bash
# OBLIGATORIO
cd @DB_SCRIPTS
./{RECREATE_CMD} # Carga limpia DEBE pasar
# Verificación
psql -d {DB_NAME} -c "\dt {schema}.*" # Tablas creadas
psql -d {DB_NAME} -c "\di {schema}.*" # Índices creados
```
### Backend (NestJS)
```bash
# OBLIGATORIO
cd @BACKEND_ROOT
npm run build # DEBE pasar
npm run lint # DEBE pasar
# Adicional
npm run test # Si hay tests, DEBEN pasar
npm run start:dev # DEBE iniciar sin errores
```
### Frontend (React)
```bash
# OBLIGATORIO
cd @FRONTEND_ROOT
npm run build # DEBE pasar
npm run lint # DEBE pasar
# Adicional
npm run typecheck # DEBE pasar
npm run dev # DEBE iniciar sin errores
```
---
## FLUJO DE VALIDACIÓN
```
TERMINAR IMPLEMENTACIÓN
│
▼
┌─────────────────────┐
│ EJECUTAR BUILD │
└──────────┬──────────┘
│
▼
┌─────────────────────┐ ┌─────────────────────┐
│ ¿BUILD PASA? │──NO──►│ CORREGIR ERRORES │
└──────────┬──────────┘ └──────────┬──────────┘
│ SÍ │
│◄────────────────────────────┘
▼
┌─────────────────────┐ ┌─────────────────────┐
│ EJECUTAR LINT │──NO──►│ CORREGIR ERRORES │
│ ¿LINT PASA? │ └──────────┬──────────┘
└──────────┬──────────┘ │
│ SÍ │
│◄────────────────────────────┘
▼
┌─────────────────────┐ ┌─────────────────────┐
│ EJECUTAR TESTS │──NO──►│ CORREGIR TESTS │
│ ¿TESTS PASAN? │ └──────────┬──────────┘
└──────────┬──────────┘ │
│ SÍ │
│◄────────────────────────────┘
▼
┌─────────────────────┐
│ ✅ TAREA COMPLETA │
└─────────────────────┘
```
---
## QUÉ HACER CUANDO FALLA
### Build Falla
```markdown
1. NO marcar tarea como completada
2. Leer el error completo
3. Identificar archivo y línea
4. Corregir el error
5. Volver a ejecutar build
6. Repetir hasta que pase
```
### Lint Falla (Errores)
```markdown
1. NO marcar tarea como completada
2. Distinguir errores de warnings
- Errores (error): DEBEN corregirse
- Warnings (warn): Pueden ignorarse (pero mejor corregir)
3. Corregir todos los errores
4. Volver a ejecutar lint
5. Repetir hasta que pase
```
### Carga Limpia Falla (DDL)
```markdown
1. NO marcar tarea como completada
2. NO ejecutar fix manual en BD
3. Leer el error de PostgreSQL
4. Corregir archivo DDL
5. Volver a ejecutar carga limpia completa
6. Repetir hasta que pase
```
### Tests Fallan
```markdown
1. NO marcar tarea como completada
2. Identificar test que falla
3. Determinar si:
a. El código tiene bug → Corregir código
b. El test está desactualizado → Actualizar test
4. Volver a ejecutar tests
5. Repetir hasta que pasen
```
---
## EXCEPCIONES (MUY LIMITADAS)
```yaml
Puede marcarse completa SIN tests:
- Si no existen tests para el módulo (pero build y lint DEBEN pasar)
- Se documenta: "Tests pendientes de crear"
Puede tener warnings de lint:
- Si son warnings menores (no errores)
- Se documenta: "N warnings de lint pendientes"
NUNCA puede marcarse completa:
- Con build fallando
- Con errores de lint
- Con carga limpia fallando
```
---
## REPORTE DE VALIDACIÓN
En toda entrega incluir:
```markdown
## Validaciones
| Validación | Comando | Resultado |
|------------|---------|-----------|
| Build | `npm run build` | ✅ Pasa / ❌ Falla |
| Lint | `npm run lint` | ✅ Pasa / ⚠️ Warnings / ❌ Errores |
| Tests | `npm run test` | ✅ Pasa / ❌ Falla / ⏭️ N/A |
| Carga Limpia | `./{RECREATE_CMD}` | ✅ Pasa / ❌ Falla / ⏭️ N/A |
**Estado:** ✅ Validaciones completas / ❌ Pendiente corrección
```
---
## CONSECUENCIAS DE IGNORAR
```
❌ Código que no compila entregado
→ Bloquea a otros agentes/desarrolladores
❌ Errores de lint ignorados
→ Código inconsistente, bugs potenciales
❌ Tests fallando ignorados
→ Regresiones, bugs en producción
❌ DDL con errores
→ BD inconsistente, datos corruptos
```
---
## CHECKLIST RÁPIDO
```
Antes de marcar CUALQUIER tarea como completada:
[ ] Build pasa sin errores
[ ] Lint pasa sin errores (warnings OK)
[ ] Tests pasan (si existen)
[ ] Carga limpia pasa (si es DDL)
[ ] Aplicación inicia correctamente
```
---
## REFERENCIAS SIMCO
- **@VALIDAR** - Proceso completo de validación
- **@OP_DDL** - Validación específica de database
- **@OP_BACKEND** - Validación específica de backend
- **@OP_FRONTEND** - Validación específica de frontend
---
**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.**
---
**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental

316
orchestration/directivas/principios/PROPAGACION-ARCHITECTURE.md Normal file
View File

@ -0,0 +1,316 @@
# PROPAGACION-ARCHITECTURE: Arquitectura de Propagacion del Workspace
**ID:** PROPAGACION-ARCHITECTURE
**Version:** 1.0.0
**Fecha:** 2026-01-13
**Autor:** CLAUDE-CAPVED
---
## Proposito
Este documento clarifica la arquitectura de propagacion del workspace, cuando usar cada mecanismo, y como se relacionan los diferentes componentes del sistema de propagacion.
---
## Jerarquia de Propagacion
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ NIVELES DE PROPAGACION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ NIVEL 0: PROVIDER │
│ ┌──────────────────┐ │
│ │ template-saas │ → Provee funcionalidades base a todos │
│ │ (v1.2.1) │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ NIVEL 1: INTERMEDIATE │
│ ┌──────────────────┐ │
│ │ erp-core │ → Extiende y adapta para verticales ERP │
│ │ (v1.3.0) │ │
│ └────────┬─────────┘ │
│ │ │
│ ├─────────────────────────────────────────────────┐ │
│ ▼ ▼ │
│ NIVEL 2: CONSUMERS NIVEL 2: INTERMEDIATE │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ erp-construccion │ │ erp-clinicas │ │
│ │ erp-mecanicas │ │ (v1.0.0) │ │
│ │ erp-retail │ └────────┬─────────┘ │
│ │ erp-vidrio │ │ │
│ └──────────────────┘ ▼ │
│ NIVEL 3: SUB-CONSUMERS │
│ ┌──────────────────┐ │
│ │ clinica-dental │ │
│ │ clinica-veterina │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## Componentes del Sistema de Propagacion
### 1. Directivas
| Componente | Ubicacion | Proposito |
|------------|-----------|-----------|
| **MODE-PROPAGATION** | `directivas/modos/` | Modo de ejecucion para propagar cambios entre proyectos |
| **TRIGGER-PROPAGACION-AUTOMATICA** | `directivas/triggers/` | Activa automaticamente en Fase D para evaluar propagacion |
| **SIMCO-PROPAGACION** | `directivas/simco/` | Propagacion de documentacion en verticales (interno) |
### 2. Referencias
| Componente | Ubicacion | Proposito |
|------------|-----------|-----------|
| **PROPAGATION-CRITERIA-MATRIX** | `referencias/` | Matriz de criterios para decidir propagacion |
| **DEPENDENCY-GRAPH** | `orchestration/` | Grafo de dependencias entre proyectos |
| **TRACEABILITY-MASTER** | `orchestration/` | Trazabilidad centralizada del workspace |
### 3. Mirrors
| Componente | Ubicacion | Proposito |
|------------|-----------|-----------|
| **MIRRORS-INDEX** | `shared/mirrors/` | Indice de todos los repositorios espejo |
| **PROPAGATION-STATUS** | `shared/mirrors/{proyecto}/` | Estado de propagacion por proyecto |
---
## Cuando Usar Cada Mecanismo
### MODE-PROPAGATION (@PROPAGATE)
**Usar cuando:**
- Necesitas propagar un cambio especifico a multiples proyectos
- Cambio en erp-core que debe ir a verticales
- Fix de seguridad que afecta multiples proyectos
- Bug fix en modulo compartido
- Actualizacion de dependencias compartidas
**Ejemplos:**
```bash
@PROPAGATE-ERP Distribuir fix de JWT a verticales
@PROPAGATE-SECURITY Fix de vulnerabilidad XSS
@PROPAGATE-CATALOG Actualizar modulo de notificaciones
```
**Flujo:**
```
Cambio en origen → CAPVED completo → Aplicar en cada destino → Validar → Documentar
```
---
### TRIGGER-PROPAGACION-AUTOMATICA
**Usar cuando:**
- Se activa automaticamente al completar Fase D
- No lo invocas directamente, el sistema lo evalua
**Cuando se activa:**
1. Completas una tarea en proyecto con propagacion (erp-core, shared/catalog)
2. El trigger evalua tipo de cambio
3. Sugiere o inicia propagacion segun reglas
**Flujo:**
```
Tarea completada → Trigger evalua → Decide accion → Notifica o propaga
```
---
### SIMCO-PROPAGACION
**Usar cuando:**
- Propagas documentacion DENTRO de un proyecto vertical
- No es para propagacion ENTRE proyectos
- Es para estructurar documentacion de modulos heredados
**Cuando se usa:**
- Al documentar un modulo heredado en una vertical
- Para asegurar que la documentacion refleja la herencia
**NO usar para:**
- Propagar codigo entre proyectos (usar MODE-PROPAGATION)
- Propagar cambios de core a verticales (usar MODE-PROPAGATION)
---
## Flujo de Decision
```
┌─────────────────────────────────────────────────────────────────┐
│ PREGUNTA: Que necesitas propagar? │
└────────────────────────────┬────────────────────────────────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌────────────────┐ ┌─────────────────┐
│ CODIGO/CAMBIO │ │ DOCUMENTACION │
│ entre proyectos│ │ dentro de │
└───────┬────────┘ │ proyecto │
│ └────────┬────────┘
▼ │
┌────────────────────┐ ▼
│ Es security fix? │ ┌─────────────────┐
└─────────┬──────────┘ │ SIMCO-PROPAGACION│
│ │ (interno) │
┌────────┴────────┐ └─────────────────┘
▼ ▼
┌─────────┐ ┌─────────┐
│ SI │ │ NO │
└────┬────┘ └────┬────┘
│ │
▼ ▼
┌──────────────┐ ┌───────────────────────┐
│ @PROPAGATE- │ │ Es bug fix? │
│ SECURITY │ └───────────┬───────────┘
│ (inmediato) │ ┌──────┴──────┐
└──────────────┘ ▼ ▼
┌─────────┐ ┌─────────┐
│ SI │ │ NO │
└────┬────┘ └────┬────┘
│ │
▼ ▼
┌──────────────┐ ┌───────────────┐
│ @PROPAGATE- │ │ @PROPAGATE │
│ ERP │ │ (evaluar) │
│ (72h SLA) │ │ │
└──────────────┘ └───────────────┘
```
---
## SLAs Unificados
| Tipo de Cambio | SLA | Prioridad | Accion |
|----------------|-----|-----------|--------|
| **Security Fix** | 24 horas | CRITICA | Propagar inmediatamente |
| **Bug Fix** | 72 horas | ALTA | Propagar con prioridad |
| **Feature** | 1 semana | MEDIA | Evaluar si aplica |
| **Refactor** | 2 semanas | BAJA | Opcional |
| **Documentacion** | Inmediato | N/A | Auto-sync via mirrors |
| **Definiciones** | Inmediato | N/A | Auto-sync via mirrors |
---
## Sistema de Mirrors
### Proposito
Los mirrors son repositorios espejo que facilitan la propagacion automatica de:
- Documentacion (README, CHANGELOG)
- Definiciones (YAML de modulos)
- Interfaces (TypeScript .d.ts)
### Mirrors Activos
| Mirror | Version | Consumidores |
|--------|---------|--------------|
| template-saas | 1.2.1 | erp-core |
| erp-core | 1.3.0 | 5 verticales + 2 sub-verticales |
| erp-clinicas | 1.0.0 | clinica-dental, clinica-veterinaria |
### Auto-Propagacion via Mirrors
```yaml
Tipo: Documentacion/Definiciones
Flujo:
1. Cambio en proyecto origen
2. Sync automatico a shared/mirrors/{proyecto}/
3. Consumidores leen del mirror
4. Actualizacion inmediata disponible
Tipo: Codigo
Flujo:
1. Cambio en proyecto origen
2. Validacion local (build+lint+tests)
3. Propagar manualmente via MODE-PROPAGATION
4. Actualizar PROPAGATION-STATUS.yml
```
---
## Trazabilidad
### Donde se registra cada propagacion
| Registro | Ubicacion | Contenido |
|----------|-----------|-----------|
| **TRACEABILITY-MASTER** | `orchestration/` | Registro centralizado de todas las propagaciones |
| **PROPAGATION-STATUS** | `shared/mirrors/{proyecto}/` | Estado por proyecto mirror |
| **MASTER_INVENTORY** | `{proyecto}/orchestration/inventarios/` | Referencia a ultima propagacion recibida |
### Formato de Registro
```yaml
propagacion:
id: "PROP-CORE-002"
fecha: "2026-01-13"
tipo: "bulk_propagation"
origen: "erp-core"
destinos:
- erp-construccion
- erp-clinicas
- erp-mecanicas-diesel
- erp-retail
- erp-vidrio-templado
sub_destinos:
- clinica-dental (via erp-clinicas)
- clinica-veterinaria (via erp-clinicas)
modulos: MGN-016 a MGN-022
estado: "completed"
```
---
## Comandos Rapidos
| Alias | Descripcion | Ejemplo |
|-------|-------------|---------|
| `@PROPAGATE-ERP` | Propagar de erp-core a verticales | `@PROPAGATE-ERP Fix de autenticacion` |
| `@PROPAGATE-CATALOG` | Propagar cambio de catalogo | `@PROPAGATE-CATALOG Actualizar notifications` |
| `@PROPAGATE-SECURITY` | Propagacion urgente de seguridad | `@PROPAGATE-SECURITY Vulnerabilidad XSS` |
| `@SYNC-MIRRORS` | Sincronizar todos los mirrors | `@SYNC-MIRRORS` |
| `@PROPAGATE-DOC` | Propagar documentacion | `@PROPAGATE-DOC {proyecto}` |
| `@PROPAGATE-DEF` | Propagar definiciones | `@PROPAGATE-DEF {proyecto}` |
| `@PROPAGATE-CODE` | Propagar codigo validado | `@PROPAGATE-CODE {proyecto}` |
---
## Errores Comunes
### 1. Confundir MODE-PROPAGATION con SIMCO-PROPAGACION
- **MODE-PROPAGATION:** Entre proyectos (erp-core → verticales)
- **SIMCO-PROPAGACION:** Dentro de un proyecto (documentacion interna)
### 2. Propagar sin validar
- **Correcto:** Siempre ejecutar build+lint+tests antes de propagar
- **Incorrecto:** Propagar directamente sin validacion
### 3. Olvidar actualizar trazabilidad
- **Correcto:** Registrar en TRACEABILITY-MASTER y PROPAGATION-STATUS
- **Incorrecto:** Propagar sin documentar
### 4. Propagar codigo no validado
- **Documentacion/Definiciones:** OK propagar inmediatamente
- **Codigo:** SIEMPRE validar antes de propagar
---
## Referencias
- `orchestration/directivas/modos/MODE-PROPAGATION.md`
- `orchestration/directivas/triggers/TRIGGER-PROPAGACION-AUTOMATICA.md`
- `orchestration/directivas/simco/SIMCO-PROPAGACION.md`
- `orchestration/referencias/PROPAGATION-CRITERIA-MATRIX.yml`
- `orchestration/TRACEABILITY-MASTER.yml`
- `orchestration/DEPENDENCY-GRAPH.yml`
- `shared/mirrors/MIRRORS-INDEX.yml`
---
*PROPAGACION-ARCHITECTURE v1.0.0 - Sistema SAAD*

510
orchestration/directivas/simco/SIMCO-GIT.md Normal file
View File

@ -0,0 +1,510 @@
# SIMCO: GIT (Control de Versiones)
**Version:** 1.2.0
**Fecha:** 2026-01-16
**Aplica a:** TODO agente que modifica codigo o documentacion
**Prioridad:** OBLIGATORIA
---
## RESUMEN EJECUTIVO
> **Todo cambio en codigo o documentacion DEBE versionarse correctamente.**
> **Commits frecuentes, atomicos y descriptivos.**
> **PUSH OBLIGATORIO al finalizar cada tarea.**
> **FETCH OBLIGATORIO antes de verificar estado.**
> **Nunca perder trabajo por falta de commits o push.**
---
## REGLA CRITICA 1: FETCH ANTES DE OPERAR
```
╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ ANTES DE CUALQUIER VERIFICACION DE ESTADO GIT: ║
║ ║
║ 1. git fetch origin ║
║ → Obtener estado actual del remoto ║
║ ║
║ 2. git log HEAD..origin/main --oneline ║
║ → Si hay output = hay commits remotos que no tienes ║
║ ║
║ 3. Si hay commits remotos: ║
║ git pull --no-recurse-submodules ║
║ → Sincronizar antes de continuar ║
║ ║
║ 4. AHORA SI: git status ║
║ → Verificar estado local ║
║ ║
║ SIN FETCH = ESTADO INCOMPLETO ║
║ (Otro agente pudo hacer cambios en otra sesion) ║
║ ║
║ Referencia: INC-2026-01-16-001 ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
```
### Secuencia Obligatoria de Verificacion
```bash
# SIEMPRE ejecutar en este orden:
git fetch origin
git log HEAD..origin/main --oneline # Si hay output, hacer pull
git pull --no-recurse-submodules # Solo si paso anterior tiene output
git status # Ahora si verificar estado local
```
---
## REGLA CRITICA 2: COMMIT + PUSH OBLIGATORIO
```
╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ TODA TAREA QUE CREA O MODIFICA ARCHIVOS DEBE TERMINAR CON: ║
║ ║
║ 1. git add . ║
║ 2. git commit -m "[ID] tipo: descripcion" ║
║ 3. git push origin {rama} ║
║ ║
║ SIN PUSH = TAREA INCOMPLETA ║
║ ║
║ En workspace con SUBMODULES: ║
║ - Commitear y push en CADA submodule afectado ║
║ - Luego commitear y push en workspace principal ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
```
### Checklist Fin de Tarea (OBLIGATORIO)
```yaml
ANTES_de_reportar_tarea_completada:
- [ ] Todos los archivos creados/modificados estan guardados
- [ ] git status muestra archivos a commitear
- [ ] git add {archivos}
- [ ] git commit -m "[TAREA-ID] tipo: descripcion"
- [ ] git push origin {rama}
- [ ] Verificar: git status muestra "nothing to commit, working tree clean"
- [ ] Verificar: git log origin/main..HEAD muestra vacio (todo pusheado)
SI_hay_SUBMODULES:
- [ ] Repetir proceso en CADA submodule modificado
- [ ] Luego actualizar referencias en workspace principal
- [ ] Push final del workspace principal
```
### Secuencia para Workspace con Submodules
```bash
# 1. Commitear en cada submodule modificado
cd projects/{submodule}
git add .
git commit -m "[TAREA-ID] tipo: descripcion"
git push origin main
# 2. Repetir para cada submodule afectado
# ...
# 3. Actualizar workspace principal
cd /home/isem/workspace-v2
git add projects/{submodule} # Actualiza referencia del submodule
git commit -m "[WORKSPACE] chore: Update submodule references"
git push origin main
# 4. Verificar todo sincronizado
git status # Debe mostrar "clean"
```
---
## PRINCIPIOS FUNDAMENTALES
```
╔══════════════════════════════════════════════════════════════════════╗
║ ║
║ "Commitear temprano, commitear frecuentemente" ║
║ ║
║ Cada commit debe: ║
║ - Representar un cambio logico completo ║
║ - Ser funcional (no romper compilacion) ║
║ - Ser reversible sin afectar otros cambios ║
║ - Tener mensaje descriptivo con ID de tarea ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## FRECUENCIA DE COMMITS
```yaml
OBLIGATORIO_commitear:
- Al finalizar cada fase (Analisis, Planeacion, Ejecucion)
- Al completar cada archivo significativo
- Cada 30-45 minutos de trabajo continuo
- Antes de lanzar subagentes
- Despues de validar trabajo de subagentes
- Antes de cambiar de tarea
- Cuando build + lint pasan
RAZON: "Minimizar perdida de trabajo en caso de error"
```
---
## FORMATO DE MENSAJE DE COMMIT
### Estructura Obligatoria
```
[{TAREA-ID}] {tipo}: {descripcion concisa}
{cuerpo opcional - descripcion detallada}
{footer opcional - referencias, breaking changes}
```
### Ejemplos Correctos
```bash
# Feature nueva
[DB-042] feat: Crear tabla projects con soporte PostGIS
# Bug fix
[BE-015] fix: Corregir validacion de codigo unico en ProjectService
# Refactor
[FE-008] refactor: Extraer componente ProjectCard de ProjectList
# Documentacion
[DB-042] docs: Actualizar DATABASE_INVENTORY con tabla projects
# Tests
[BE-015] test: Agregar tests unitarios para ProjectService
# Subtarea
[DB-042-SUB-001] feat: Implementar indices para tabla projects
```
### Ejemplos Incorrectos
```bash
# Sin ID de tarea
fix: Corregir bug
# Muy vago
[BE-015] update: Cambios varios
# Demasiado largo en primera linea
[DB-042] feat: Crear tabla projects con todas las columnas necesarias incluyendo soporte para PostGIS y configuracion de indices compuestos para optimizar queries
# Sin tipo
[FE-008] Mejorar componente
```
---
## TIPOS DE COMMITS
| Tipo | Uso | Ejemplo |
|------|-----|---------|
| `feat` | Nueva funcionalidad | `[DB-042] feat: Agregar soporte PostGIS` |
| `fix` | Correccion de bug | `[BE-015] fix: Resolver error en constraint` |
| `refactor` | Refactorizacion sin cambio funcional | `[FE-008] refactor: Mejorar estructura componentes` |
| `docs` | Solo documentacion | `[DB-042] docs: Actualizar README con schema` |
| `test` | Agregar/modificar tests | `[BE-015] test: Agregar tests para ProjectService` |
| `chore` | Tareas de mantenimiento | `[DB-042] chore: Actualizar dependencias` |
| `style` | Formato/estilo (sin cambio logico) | `[FE-008] style: Aplicar prettier` |
| `perf` | Mejora de performance | `[DB-042] perf: Agregar indice compuesto` |
| `build` | Cambios en build/deps | `[BE-015] build: Actualizar TypeORM a v0.3` |
| `ci` | Cambios en CI/CD | `[INFRA-001] ci: Agregar workflow de tests` |
---
## COMMITS ATOMICOS
### Que es un Commit Atomico
```yaml
atomico:
- Representa UN cambio logico completo
- Es funcional (build pasa)
- Es reversible individualmente
- No mezcla cambios no relacionados
NO_atomico:
- Multiples cambios no relacionados
- Trabajo incompleto (excepto WIP explicito)
- Mezcla de fix y feat
- Cambios en multiples features
```
### Ejemplo de Atomicidad
```bash
# CORRECTO - Commits atomicos separados
[DB-042] feat: Crear tabla projects
[DB-042] feat: Agregar indices a tabla projects
[DB-042] feat: Crear seeds para projects
[DB-042] docs: Actualizar inventario con tabla projects
# INCORRECTO - Un commit masivo
[DB-042] feat: Crear tabla projects con indices, seeds y actualizacion de inventario
```
---
## FLUJO DE TRABAJO GIT
### Antes de Empezar Tarea
```bash
# 1. Asegurar rama actualizada
git fetch origin
git pull origin main
# 2. Crear rama de trabajo (si aplica)
git checkout -b feature/{TAREA-ID}-descripcion-corta
# 3. Verificar estado limpio
git status
```
### Durante la Tarea
```bash
# 1. Hacer cambios
# ... editar archivos ...
# 2. Verificar que build pasa
npm run build
npm run lint
# 3. Agregar cambios
git add {archivos especificos}
# o para todos los cambios relacionados:
git add .
# 4. Commit con mensaje descriptivo
git commit -m "[TAREA-ID] tipo: descripcion"
# 5. Repetir para cada cambio logico
```
### Al Completar Tarea
```bash
# 1. Verificar historial
git log --oneline -5
# 2. Push a remoto
git push origin {rama}
# 3. Crear PR si aplica
gh pr create --title "[TAREA-ID] Descripcion" --body "..."
```
---
## CHECKLIST PRE-COMMIT
```yaml
ANTES_de_cada_commit:
- [ ] Build pasa sin errores
- [ ] Lint pasa sin errores criticos
- [ ] Tests pasan (si existen)
- [ ] Cambios son logicamente completos
- [ ] No hay archivos no deseados (node_modules, .env, etc.)
- [ ] Mensaje sigue formato correcto
VERIFICAR:
git status # Ver archivos modificados
git diff # Ver cambios en detalle
git diff --cached # Ver cambios staged
```
---
## ERRORES COMUNES
| Error | Consecuencia | Solucion |
|-------|--------------|----------|
| No commitear frecuentemente | Perdida de trabajo | Commit cada 30-45 min |
| Commits masivos | Dificil revertir | Commits atomicos |
| Mensajes vagos | Historial incomprensible | Seguir formato |
| Commit con build roto | Bloquea CI/CD | Verificar antes de commit |
| Olvidar ID de tarea | Perdida de trazabilidad | Siempre incluir [TAREA-ID] |
| Commitear secretos | Brecha de seguridad | Verificar .gitignore |
---
## ARCHIVOS A IGNORAR (.gitignore)
```yaml
SIEMPRE_ignorar:
- node_modules/
- .env
- .env.*
- dist/
- build/
- coverage/
- *.log
- .DS_Store
- *.tmp
- *.cache
NUNCA_commitear:
- Credenciales
- API keys
- Passwords
- Certificados privados
- Archivos de configuracion local
```
---
## RAMAS (BRANCHING)
### Convencion de Nombres
```yaml
ramas:
feature: feature/{TAREA-ID}-descripcion-corta
bugfix: bugfix/{TAREA-ID}-descripcion-corta
hotfix: hotfix/{TAREA-ID}-descripcion-corta
release: release/v{X.Y.Z}
ejemplos:
- feature/DB-042-crear-tabla-projects
- bugfix/BE-015-fix-validacion
- hotfix/SEC-001-fix-xss
- release/v2.1.0
```
### Flujo de Ramas
```
main (produccion)
│
├─── develop (desarrollo)
│ │
│ ├─── feature/DB-042-*
│ │ └── merge a develop
│ │
│ ├─── feature/BE-015-*
│ │ └── merge a develop
│ │
│ └── release/v2.1.0
│ └── merge a main + tag
│
└─── hotfix/SEC-001-*
└── merge a main + develop
```
---
## REVERTIR CAMBIOS
### Revertir Ultimo Commit (no pusheado)
```bash
# Mantener cambios en working directory
git reset --soft HEAD~1
# Descartar cambios completamente
git reset --hard HEAD~1
```
### Revertir Commit ya Pusheado
```bash
# Crear commit de reversion (seguro)
git revert {commit-hash}
git push
```
### Deshacer Cambios en Archivo
```bash
# Descartar cambios no staged
git checkout -- {archivo}
# Descartar cambios staged
git reset HEAD {archivo}
git checkout -- {archivo}
```
---
## SITUACIONES ESPECIALES
### Work in Progress (WIP)
```bash
# Cuando necesitas commitear trabajo incompleto
git commit -m "[TAREA-ID] WIP: descripcion de estado actual"
# Luego, completar y hacer commit final
# (opcional: squash commits WIP antes de PR)
```
### Antes de Lanzar Subagente
```bash
# SIEMPRE commitear antes de delegar
git add .
git commit -m "[TAREA-ID] chore: Estado antes de delegacion a {SubAgente}"
```
### Despues de Validar Subagente
```bash
# Commitear resultado de subagente
git add .
git commit -m "[TAREA-ID-SUB-XXX] tipo: Resultado de {SubAgente}"
```
---
## VALIDACION DE COMMITS
### Verificar Historial
```bash
# Ver ultimos commits
git log --oneline -10
# Ver commits de tarea especifica
git log --oneline --grep="DB-042"
# Ver cambios de un commit
git show {commit-hash}
```
### Verificar Formato de Mensaje
```yaml
formato_valido:
- Tiene [TAREA-ID] al inicio
- Tiene tipo valido (feat, fix, etc.)
- Descripcion concisa (<72 caracteres primera linea)
- No tiene errores de ortografia graves
verificar_manualmente:
git log --oneline -1
# Debe mostrar: {hash} [TAREA-ID] tipo: descripcion
```
---
## REFERENCIAS
- **Principio de Validacion:** @PRINCIPIOS/PRINCIPIO-VALIDACION-OBLIGATORIA.md
- **Documentar:** @SIMCO/SIMCO-DOCUMENTAR.md
- **Crear:** @SIMCO/SIMCO-CREAR.md
---
**Version:** 1.0.0 | **Sistema:** SIMCO | **Mantenido por:** Tech Lead

829
orchestration/directivas/simco/SIMCO-TAREA.md Normal file
View File

@ -0,0 +1,829 @@
# SIMCO: CICLO DE VIDA DE TAREAS (CAPVED)
**Versión:** 1.1.0
**Sistema:** SIMCO - Gestión de Tareas con CAPVED
**Propósito:** Definir el proceso completo para toda HU/Tarea que modifica código o documentación
**Actualizado:** 2025-12-08
---
## PRINCIPIO FUNDAMENTAL
> **Toda tarea que genera commit DEBE pasar por el ciclo CAPVED completo.**
> **Si algo aparece fuera del alcance, se registra y genera HU nueva.**
> **NUEVO: Antes de CAPVED, ejecutar FASE 0 para identificar nivel y contexto.**
---
## FASE 0: IDENTIFICACIÓN DE NIVEL (NUEVA - CRÍTICA)
**OBLIGATORIO antes de iniciar CAPVED**
### 0.1 Determinar Nivel Jerárquico
```yaml
Paso_1: Identificar en qué nivel del workspace estás trabajando
NIVEL_0_WORKSPACE:
ruta: "/workspace/orchestration/"
identificador: "Es directiva global o índice de workspace"
NIVEL_1_CORE:
ruta: "/workspace/core/"
identificador: "Es funcionalidad de catálogo o directiva"
NIVEL_2A_STANDALONE:
ruta: "/workspace/projects/{proyecto}/"
identificador: "NO tiene subcarpeta verticales/"
ejemplos: "gamilit, trading-platform, betting-analytics"
NIVEL_2B_SUITE:
ruta: "/workspace/projects/{suite}/"
identificador: "TIENE subcarpeta apps/verticales/"
ejemplo: "erp-suite"
NIVEL_2B1_SUITE_CORE:
ruta: "/workspace/projects/{suite}/apps/erp-core/"
identificador: "Es el núcleo de la suite"
NIVEL_2B2_VERTICAL:
ruta: "/workspace/projects/{suite}/apps/verticales/{vertical}/"
identificador: "Es vertical especializada"
ejemplos: "construccion, vidrio-templado, clinicas, retail"
NIVEL_3_CATALOGO:
ruta: "/workspace/shared/catalog/{funcionalidad}/"
identificador: "Es funcionalidad reutilizable"
```
### 0.2 Cargar Contexto del Nivel
```yaml
Archivos_a_leer_según_nivel:
STANDALONE:
- orchestration/templates/TEMPLATE-CONTEXTO-PROYECTO.md
- orchestration/templates/HERENCIA-SIMCO.md
- orchestration/inventarios/MASTER_INVENTORY.yml
VERTICAL:
- orchestration/templates/TEMPLATE-CONTEXTO-PROYECTO.md
- orchestration/templates/HERENCIA-SIMCO.md
- orchestration/templates/HERENCIA-ERP-CORE-TEMPLATE.md
- orchestration/inventarios/MASTER_INVENTORY.yml
SUITE_CORE:
- orchestration/templates/TEMPLATE-CONTEXTO-PROYECTO.md
- orchestration/inventarios/MASTER_INVENTORY.yml
- orchestration/inventarios/DEVENV-MASTER-INVENTORY.yml
```
### 0.3 Identificar Ruta de Propagación
```yaml
Según_tu_nivel_actual:
STANDALONE → propagar a:
- WORKSPACE (orchestration/WORKSPACE-STATUS.md)
VERTICAL → propagar a:
- SUITE (../../../orchestration/inventarios/)
- WORKSPACE (orchestration/WORKSPACE-STATUS.md)
SUITE_CORE → propagar a:
- SUITE (../../orchestration/inventarios/)
- WORKSPACE (orchestration/WORKSPACE-STATUS.md)
- VERTICALES (si afecta herencia)
CATALOGO → propagar a:
- CORE (inventarios/CORE_INVENTORY.yml)
- CONSUMIDORES (CATALOG-USAGE-TRACKING.yml)
```
### 0.4 Registrar Identificación
```yaml
# Resultado de Fase 0 (incluir en reporte)
fase_0_identificacion:
nivel: "{NIVEL_IDENTIFICADO}"
proyecto: "{NOMBRE}"
path: "{RUTA_COMPLETA}"
propagacion_a:
- "{nivel_superior_1}"
- "{nivel_superior_2}"
contexto_cargado:
- TEMPLATE-CONTEXTO-PROYECTO.md ✓
- HERENCIA-SIMCO.md ✓
- MASTER_INVENTORY.yml ✓
herencia_especifica: "{Si aplica: HERENCIA-ERP-CORE-TEMPLATE.md}"
```
### 0.5 Verificar Catálogo
```yaml
ANTES_de_proceder_a_CAPVED:
verificar: "¿Lo que voy a crear existe en @CATALOG?"
comando: "Buscar en shared/catalog/CATALOG-INDEX.yml"
SI_EXISTE:
- Leer SIMCO-REUTILIZAR.md
- Adaptar en lugar de crear
- Documentar adaptación
SI_NO_EXISTE:
- Proceder con CAPVED normal
- Considerar contribuir al catálogo al finalizar
```
---
## CUÁNDO USAR ESTE SIMCO
```yaml
USAR_SIMCO_TAREA_cuando:
- Recibes una HU o tarea técnica
- La tarea involucra modificar código
- La tarea involucra modificar documentación
- La tarea generará uno o más commits
- Cualquier trabajo que no sea puramente exploratorio
NO_USAR_cuando:
- Solo estás investigando/explorando (usa SIMCO-BUSCAR)
- Solo estás consultando información
- Es un spike sin implementación
```
---
## FLUJO COMPLETO CAPVED
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ ENTRADA: HU o Tarea Técnica │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ FASE C: CONTEXTO (~5 min) │ │
│ │ ──────────────────────────── │ │
│ │ 1. Identificar proyecto/módulo/epic │ │
│ │ 2. Clasificar tipo de tarea │ │
│ │ 3. Registrar origen │ │
│ │ 4. Cargar contexto SIMCO (CCA) │ │
│ │ 5. Vincular documentos relevantes │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ FASE A: ANÁLISIS (~15 min) │ │
│ │ ────────────────────────── │ │
│ │ 1. Entender comportamiento deseado (negocio) │ │
│ │ 2. Identificar restricciones (seguridad/perf/UX) │ │
│ │ 3. Mapear objetos impactados (BD, BE, FE, otros) │ │
│ │ 4. Identificar dependencias (HUs bloqueantes/bloqueadas) │ │
│ │ 5. Detectar riesgos │ │
│ │ → SALIDA: Reporte de análisis │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ FASE P: PLANEACIÓN (~10 min) │ │
│ │ ───────────────────────────── │ │
│ │ 1. Desglosar en subtareas por dominio │ │
│ │ 2. Establecer orden de ejecución │ │
│ │ 3. Definir criterios de aceptación │ │
│ │ 4. Planificar pruebas │ │
│ │ 5. Asignar agentes/subagentes (si aplica) │ │
│ │ → SALIDA: Plan de ejecución │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ FASE V: VALIDACIÓN (~5 min) ⚠️ NO DELEGAR │ │
│ │ ──────────────────────────────────────────── │ │
│ │ 1. ¿Todo lo de A tiene acción en P? │ │
│ │ 2. ¿Dependencias resueltas o planificadas? │ │
│ │ 3. ¿Criterios cubren riesgos? │ │
│ │ 4. ¿Hay scope creep? → Registrar + crear HU derivada │ │
│ │ → GATE: Solo pasa si TODO cuadra │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ ¿VALIDACIÓN OK? │ │
│ └─────────┬─────────┘ │
│ NO │ │ SÍ │
│ ▼ ▼ │
│ ┌────────────┐ ┌──────────────────────────────────────────┐ │
│ │ AJUSTAR │ │ FASE E: EJECUCIÓN (variable) │ │
│ │ A o P │ │ ───────────────────────────── │ │
│ │ y volver │ │ 1. Actualizar docs/ PRIMERO │ │
│ │ a V │ │ 2. Ejecutar subtareas en orden │ │
│ └────────────┘ │ 3. Validar build/lint por subtarea │ │
│ │ 4. Registrar progreso │ │
│ │ 5. Usar SIMCO correspondientes │ │
│ │ → SALIDA: Código implementado │ │
│ └──────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ FASE D: DOCUMENTACIÓN (~10 min) │ │
│ │ ─────────────────────────────── │ │
│ │ 1. Actualizar diagramas/modelos │ │
│ │ 2. Actualizar specs técnicas │ │
│ │ 3. Crear ADR (si decisión arquitectónica) │ │
│ │ 4. Actualizar inventarios │ │
│ │ 5. Actualizar trazas │ │
│ │ 6. Vincular HUs derivadas │ │
│ │ 7. Registrar lecciones aprendidas │ │
│ │ → GATE: HU NO está Done sin esto │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ │
│ SALIDA: HU Completada, Documentada, Trazable │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## FASE C: CONTEXTO (Detalle)
### C.1 Identificar Proyecto/Módulo/Epic
```yaml
Contexto_Obligatorio:
proyecto: "{nombre del proyecto}"
ruta_proyecto: "projects/{proyecto}/"
modulo: "{nombre del módulo afectado}"
epic_padre: "{EPIC-ID} - {nombre}"
feature_padre: "{FEATURE-ID} - {nombre}" # si aplica
```
### C.2 Clasificar Tipo de Tarea
```yaml
Tipos_de_Tarea:
feature: "Nueva funcionalidad"
enhancement: "Mejora a funcionalidad existente"
fix: "Corrección de bug"
refactor: "Reestructuración sin cambio funcional"
spike: "Investigación técnica"
doc-only: "Solo documentación"
tech-debt: "Pago de deuda técnica"
security: "Corrección de seguridad"
performance: "Optimización de rendimiento"
```
### C.3 Registrar Origen
```yaml
Origenes_de_Tarea:
plan-original: "Parte del plan de proyecto/sprint"
descubrimiento: "Detectada durante otra tarea"
incidencia: "Reportada por usuario/QA"
mejora-continua: "Identificada en retrospectiva"
dependencia: "Requerida por otra HU"
```
### C.4 Cargar Contexto SIMCO (CCA)
```
Seguir protocolo de SIMCO-INICIALIZACION.md:
1. Leer principios fundamentales (4 ahora con CAPVED)
2. Leer perfil del agente
3. Leer CONTEXTO-PROYECTO.md
4. Leer inventarios relevantes
5. Cargar SIMCO de operación según tipo de tarea
```
### C.5 Vincular Documentos Relevantes
```yaml
Documentos_a_Vincular:
docs_proyecto:
- "docs/{fase}/{epic}/README.md"
- "docs/{fase}/{epic}/requerimientos/{archivo}.md"
- "docs/{fase}/{epic}/especificaciones/{archivo}.md"
docs_tecnicos:
- "docs/95-guias-desarrollo/{relevantes}.md"
- "docs/97-adr/{relacionados}.md"
orchestration:
- "orchestration/inventarios/{relevantes}.yml"
- "orchestration/trazas/TRAZA-{tipo}.md"
```
---
## FASE A: ANÁLISIS (Detalle)
### A.1 Comportamiento Deseado (Negocio)
```yaml
Preguntas_de_Negocio:
- "¿Qué debe poder hacer el usuario al completar esta HU?"
- "¿Qué problema de negocio resuelve?"
- "¿Cuál es el criterio de éxito desde perspectiva de usuario?"
- "¿Hay casos de uso específicos documentados?"
Formato_Respuesta:
como: "{rol de usuario}"
quiero: "{acción deseada}"
para: "{beneficio/valor}"
```
### A.2 Restricciones
```yaml
Restricciones_a_Identificar:
seguridad:
- "¿Requiere autenticación?"
- "¿Requiere autorización por rol?"
- "¿Maneja datos sensibles?"
- "¿Aplica RLS?"
performance:
- "¿Volumen esperado de datos?"
- "¿Tiempo de respuesta esperado?"
- "¿Requiere paginación?"
- "¿Requiere caché?"
ux:
- "¿Hay wireframes/mockups?"
- "¿Estados de carga definidos?"
- "¿Manejo de errores definido?"
- "¿Responsive requerido?"
```
### A.3 Mapear Objetos Impactados
```yaml
Objetos_por_Capa:
database:
schemas: [] # Schemas afectados
tablas: [] # Tablas a crear/modificar
vistas: [] # Vistas afectadas
funciones: [] # Funciones a crear/modificar
indices: [] # Índices necesarios
triggers: [] # Triggers afectados
rls_policies: [] # Políticas RLS
backend:
modulos: [] # Módulos NestJS
entities: [] # Entities TypeORM
services: [] # Services
controllers: [] # Controllers
dtos: [] # DTOs (Request/Response)
guards: [] # Guards de autorización
pipes: [] # Pipes de validación
frontend:
paginas: [] # Páginas/rutas
componentes: [] # Componentes React
hooks: [] # Custom hooks
stores: [] # Stores Zustand
types: [] # TypeScript types/interfaces
services: [] # Services de API
otros:
proyectos: [] # Otros proyectos afectados
integraciones: [] # Integraciones externas
jobs: [] # Jobs/colas
caches: [] # Caché a invalidar
```
### A.4 Identificar Dependencias
```yaml
Dependencias:
bloquea_a: # Esta HU bloquea a otras
- hu_id: "HU-XXX"
razon: "Necesita la tabla que creo"
bloqueada_por: # Esta HU depende de otras
- hu_id: "HU-YYY"
razon: "Necesito el endpoint de auth"
estado: "completada | en-progreso | pendiente"
relacionadas: # HUs relacionadas (no bloqueo directo)
- hu_id: "HU-ZZZ"
relacion: "Mismo módulo"
```
### A.5 Detectar Riesgos
```yaml
Riesgos_Identificados:
- id: "R1"
descripcion: "Cambio en tabla users afecta auth de todos los tenants"
probabilidad: "alta | media | baja"
impacto: "alto | medio | bajo"
mitigacion: "Ejecutar en horario de bajo tráfico, tener rollback listo"
```
---
## FASE P: PLANEACIÓN (Detalle)
### P.1 Desglosar en Subtareas
```yaml
Subtareas:
documentacion: # SIEMPRE PRIMERO
- id: "ST-001"
descripcion: "Actualizar spec de API en docs/"
artefactos: ["docs/.../.md"]
database:
- id: "ST-002"
descripcion: "Crear tabla users en schema auth"
artefactos: ["ddl/schemas/auth/tables/users.sql"]
agente: "Database-Agent"
backend:
- id: "ST-003"
descripcion: "Crear UserEntity alineada con DDL"
artefactos: ["src/modules/users/entities/user.entity.ts"]
agente: "Backend-Agent"
depende_de: ["ST-002"]
- id: "ST-004"
descripcion: "Crear UsersService con CRUD"
artefactos: ["src/modules/users/users.service.ts"]
agente: "Backend-Agent"
depende_de: ["ST-003"]
frontend:
- id: "ST-005"
descripcion: "Crear UserList component"
artefactos: ["src/components/users/UserList.tsx"]
agente: "Frontend-Agent"
depende_de: ["ST-004"]
validacion: # SIEMPRE AL FINAL
- id: "ST-006"
descripcion: "Validación final build/lint/tests"
agente: "Ejecutar directamente"
```
### P.2 Orden de Ejecución
```
1. Documentación (docs/ actualizados)
↓
2. Database (DDL, migraciones)
↓
3. Backend (Entities → Services → Controllers)
↓
4. Frontend (Types → Hooks → Components → Pages)
↓
5. Validación (build, lint, tests)
↓
6. Documentación final (inventarios, trazas)
```
### P.3 Criterios de Aceptación
```yaml
Criterios_de_Aceptacion:
funcionales:
- "Usuario puede crear registro"
- "Usuario puede listar registros con paginación"
- "Usuario puede editar registro existente"
- "Usuario puede eliminar registro (soft delete)"
tecnicos:
- "Build pasa sin errores"
- "Lint pasa sin errores"
- "Tests unitarios cubren >80%"
- "API documentada en Swagger"
documentacion:
- "Inventarios actualizados"
- "Trazas registradas"
- "ADR creado (si aplica)"
```
### P.4 Plan de Pruebas
```yaml
Plan_de_Pruebas:
unitarias:
- "Service: CRUD operations"
- "Guards: permission checks"
integracion:
- "API: endpoints responden correctamente"
- "DB: datos persisten correctamente"
e2e:
- "Flujo completo crear-editar-eliminar"
regresion:
- "Auth sigue funcionando"
- "Otros módulos no afectados"
```
---
## FASE V: VALIDACIÓN (Detalle)
### V.1 Verificar Cobertura Análisis → Plan
```yaml
Verificacion_Cobertura:
objetos_database:
- objeto: "tabla users"
en_analisis: true
en_plan: "ST-002"
✓ CUBIERTO
objetos_backend:
- objeto: "UserEntity"
en_analisis: true
en_plan: "ST-003"
✓ CUBIERTO
# Si algo en Análisis NO tiene subtarea en Plan:
gap_detectado:
- objeto: "índice en email"
en_analisis: true
en_plan: false
accion: "Agregar subtarea ST-002b"
```
### V.2 Verificar Dependencias
```yaml
Verificacion_Dependencias:
- hu_dependencia: "HU-YYY"
estado: "completada"
✓ LISTA
- hu_dependencia: "HU-ZZZ"
estado: "pendiente"
⚠️ BLOQUEADOR
accion: "Esperar o crear subtarea previa"
```
### V.3 Detectar Scope Creep
```yaml
Scope_Creep_Detectado:
- item: "Se necesita también endpoint de búsqueda"
parte_de_hu_original: false
accion: "CREAR HU DERIVADA"
hu_derivada:
id: "DERIVED-HU-001-001"
descripcion: "Endpoint de búsqueda de usuarios"
prioridad: "P2"
```
### V.4 Gate de Validación
```
CHECKLIST GATE:
[ ] Todo objeto de Análisis tiene subtarea en Plan
[ ] Todas las dependencias están resueltas o planificadas
[ ] Criterios de aceptación cubren todos los riesgos
[ ] Scope creep registrado y HUs derivadas creadas
[ ] No hay gaps sin resolver
→ Si TODO marcado: PROCEDER A EJECUCIÓN
→ Si algo falta: VOLVER A AJUSTAR A o P
```
---
## FASE E: EJECUCIÓN (Detalle)
### E.1 Actualizar docs/ PRIMERO
```yaml
Antes_de_Codigo:
- Actualizar specs de API
- Actualizar diagramas de entidades
- Actualizar documentación de módulo
- Verificar que docs/ refleja lo que se va a implementar
```
### E.2 Ejecutar Subtareas en Orden
Para cada subtarea:
```yaml
Por_Subtarea:
1_iniciar:
- Marcar subtarea "en progreso"
- Cargar SIMCO correspondiente (CREAR/MODIFICAR/DDL/etc)
2_implementar:
- Seguir checklist del SIMCO
- Aplicar principios (doc-primero, anti-dup, validación)
- Generar código/cambios
3_validar:
- Ejecutar build
- Ejecutar lint
- Verificar que compila
4_registrar:
- Marcar subtarea "completada"
- Notas de lo implementado
- Desviaciónes (si las hubo)
5_siguiente:
- Pasar a siguiente subtarea
```
### E.3 Usar SIMCO Correspondientes
```yaml
SIMCO_por_Subtarea:
crear_tabla: "@SIMCO-CREAR + @SIMCO-DDL"
crear_entity: "@SIMCO-CREAR + @SIMCO-BACKEND"
crear_componente: "@SIMCO-CREAR + @SIMCO-FRONTEND"
modificar_algo: "@SIMCO-MODIFICAR + @SIMCO-{dominio}"
validar: "@SIMCO-VALIDAR"
```
---
## FASE D: DOCUMENTACIÓN (Detalle)
### D.1 Actualizar Diagramas/Modelos
```yaml
Diagramas_a_Actualizar:
- tipo: "ERD"
ubicacion: "docs/{epic}/diseño/erd.md"
cambio: "Agregar tabla users"
- tipo: "Arquitectura"
ubicacion: "docs/00-vision-general/arquitectura.md"
cambio: "Agregar módulo users" # si aplica
```
### D.2 Actualizar Specs Técnicas
```yaml
Specs_a_Actualizar:
- tipo: "API"
ubicacion: "docs/{epic}/especificaciones/api-users.md"
cambio: "Documentar endpoints CRUD"
- tipo: "BD"
ubicacion: "docs/{epic}/especificaciones/modelo-datos.md"
cambio: "Agregar tabla users"
```
### D.3 Crear ADR (si aplica)
```yaml
ADR_Requerido_Si:
- "Se tomó decisión arquitectónica importante"
- "Se eligió tecnología/librería nueva"
- "Se cambió patrón establecido"
- "Se hizo trade-off significativo"
Ubicacion: "docs/97-adr/ADR-{NNN}-{titulo}.md"
```
### D.4 Actualizar Inventarios
```yaml
Inventarios_a_Actualizar:
- archivo: "orchestration/inventarios/DATABASE_INVENTORY.yml"
agregar: "Nueva tabla users en schema auth"
- archivo: "orchestration/inventarios/BACKEND_INVENTORY.yml"
agregar: "Nuevo módulo users"
- archivo: "orchestration/inventarios/FRONTEND_INVENTORY.yml"
agregar: "Nuevo componente UserList"
```
### D.5 Actualizar Trazas
```yaml
Traza_a_Registrar:
archivo: "orchestration/trazas/TRAZA-TAREAS-{tipo}.md"
entrada:
fecha: "2025-12-08"
hu_id: "HU-001"
descripcion: "CRUD de usuarios"
archivos_creados: [lista]
archivos_modificados: [lista]
agente: "Backend-Agent"
duracion: "2h"
notas: "Sin incidencias"
```
### D.6 Vincular HUs Derivadas
```yaml
HUs_Derivadas:
- id: "DERIVED-HU-001-001"
descripcion: "Endpoint de búsqueda de usuarios"
origen: "HU-001"
detectado_en: "Fase V - Validación"
estado: "pendiente"
prioridad: "P2"
```
### D.7 Registrar Lecciones Aprendidas
```yaml
Lecciones_Aprendidas:
que_funciono_bien:
- "Seguir orden DB → BE → FE evitó retrabajos"
- "Validar contra Swagger antes de FE ahorró tiempo"
que_se_puede_mejorar:
- "Definir tipos compartidos desde el inicio"
para_futuras_HUs:
- "En módulos CRUD, siempre incluir paginación desde V1"
```
### D.8 Gate Final
```
CHECKLIST DOCUMENTACIÓN:
[ ] Diagramas actualizados
[ ] Specs técnicas actualizadas
[ ] ADR creado (si aplica)
[ ] Inventarios actualizados
[ ] Trazas registradas
[ ] HUs derivadas vinculadas
[ ] Lecciones aprendidas registradas
→ Si TODO marcado: HU COMPLETADA
→ Si algo falta: COMPLETAR ANTES DE CERRAR
```
---
## TEMPLATE DE REGISTRO RÁPIDO
```yaml
# Registro CAPVED para HU-{ID}
# ────────────────────────────
hu_id: "HU-XXX"
titulo: "Título de la HU"
fecha_inicio: "YYYY-MM-DD"
fecha_fin: "YYYY-MM-DD"
contexto:
proyecto: ""
modulo: ""
epic: ""
tipo: "feature | fix | refactor | etc"
origen: "plan | descubrimiento | incidencia"
analisis:
objetos_impactados: N
dependencias: N
riesgos: N
planeacion:
subtareas: N
agentes_asignados: []
validacion:
gaps_detectados: N
scope_creep: "sí | no"
hus_derivadas: N
ejecucion:
subtareas_completadas: "N/N"
build_status: "✓ | ✗"
lint_status: "✓ | ✗"
documentacion:
inventarios: "✓ | ✗"
trazas: "✓ | ✗"
adr: "✓ | N/A"
lecciones: "✓ | ✗"
estado_final: "COMPLETADA | EN_PROGRESO | BLOQUEADA"
```
---
## REFERENCIAS
| Documento | Propósito |
|-----------|-----------|
| `PRINCIPIO-CAPVED.md` | Declaración del principio |
| `SIMCO-INICIALIZACION.md` | Protocolo CCA |
| `TEMPLATE-TAREA-CAPVED.md` | Template completo para tracking |
| `TEMPLATE-ANALISIS.md` | Template de análisis |
| `TEMPLATE-PLAN.md` | Template de planeación |
| `TEMPLATE-VALIDACION.md` | Template de validación |
---
**Versión:** 1.0.0 | **Sistema:** SIMCO + CAPVED | **Tipo:** Directiva de Proceso

394
orchestration/directivas/simco/SIMCO-VALIDAR.md Normal file
View File

@ -0,0 +1,394 @@
# SIMCO: VALIDAR
**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Aplica a:** TODO agente antes de marcar una tarea como completada
**Prioridad:** OBLIGATORIA - NO SE PUEDE OMITIR
---
## RESUMEN EJECUTIVO
> **NINGUNA tarea se marca como completada sin pasar TODAS las validaciones.**
> **Si una validación falla, la tarea NO está completa.**
---
## PRINCIPIO FUNDAMENTAL
```
╔══════════════════════════════════════════════════════════════════════╗
║ BUILD PASA + LINT PASA + TESTS PASAN = TAREA PUEDE COMPLETARSE ║
║ CUALQUIER FALLO = TAREA NO COMPLETADA ║
╚══════════════════════════════════════════════════════════════════════╝
```
---
## CHECKLIST UNIVERSAL DE VALIDACIÓN
```
VALIDACIONES TÉCNICAS (OBLIGATORIAS)
├── [ ] 1. Build compila sin errores
├── [ ] 2. Lint pasa sin errores críticos
├── [ ] 3. Tests pasan (si existen)
└── [ ] 4. Aplicación inicia correctamente
VALIDACIONES DE COHERENCIA
├── [ ] 5. Código alineado con documentación
├── [ ] 6. Sin duplicados creados
├── [ ] 7. Convenciones seguidas
└── [ ] 8. Inventarios actualizados
VALIDACIONES DE INTEGRACIÓN
├── [ ] 9. Coherencia entre capas (DB↔BE↔FE)
└── [ ] 10. APIs funcionan correctamente
```
---
## VALIDACIONES POR CAPA
> **Definiciones canónicas disponibles:**
> - @DEF_VAL_BE → `_definitions/validations/VALIDATION-BACKEND.md`
> - @DEF_VAL_FE → `_definitions/validations/VALIDATION-FRONTEND.md`
> - @DEF_VAL_DDL → `_definitions/validations/VALIDATION-DDL.md`
> - @DEF_VAL_DEVOPS → `_definitions/validations/VALIDATION-DEVOPS.md`
### Database (DDL)
> **Definición canónica:** @DEF_VAL_DDL
**Comando obligatorio:**
```bash
# Carga limpia COMPLETA
cd @DB_SCRIPTS
./{RECREATE_CMD}
```
**Criterios de éxito:**
```
✅ Script ejecuta sin errores
✅ Todas las tablas se crean
✅ Todos los índices se crean
✅ Constraints se aplican
✅ Seeds se cargan (si existen)
✅ Integridad referencial OK
```
**Verificación post-creación:**
```bash
# Verificar tablas
psql -d {DB_NAME} -c "\dt {schema}.*"
# Verificar índices
psql -d {DB_NAME} -c "\di {schema}.*"
# Verificar estructura
psql -d {DB_NAME} -c "\d {schema}.{tabla}"
# Test de insert
psql -d {DB_NAME} -c "INSERT INTO {schema}.{tabla} (...) VALUES (...);"
```
**Si falla:**
```
🛑 NO marcar como completada
1. Identificar error en DDL
2. Corregir archivo DDL (NO fix manual en BD)
3. Re-ejecutar carga limpia
4. Solo entonces continuar
```
---
### Backend (NestJS/TypeScript)
> **Definición canónica:** @DEF_VAL_BE
**Comandos obligatorios:**
```bash
cd @BACKEND_ROOT
# 1. Build (OBLIGATORIO)
npm run build
# ✅ Debe completar sin errores
# 2. Lint (OBLIGATORIO)
npm run lint
# ✅ Debe pasar o corregir errores
# 3. Tests (si existen)
npm run test
# ✅ Deben pasar
# 4. Iniciar aplicación
npm run start:dev
# ✅ Debe iniciar sin errores de runtime
```
**Criterios de éxito:**
```
✅ TypeScript compila sin errores
✅ ESLint sin errores (warnings aceptables)
✅ Tests unitarios pasan
✅ Aplicación inicia
✅ Endpoints responden
```
**Verificación de endpoints:**
```bash
# Verificar health
curl http://localhost:3000/api/health
# Verificar endpoint creado
curl http://localhost:3000/api/{recurso}
# Verificar Swagger
curl http://localhost:3000/api/docs
```
**Si falla:**
```
🛑 NO marcar como completada
1. Revisar errores de TypeScript
2. Corregir código
3. Re-ejecutar build + lint
4. Solo entonces continuar
```
---
### Frontend (React/TypeScript)
> **Definición canónica:** @DEF_VAL_FE
**Comandos obligatorios:**
```bash
cd @FRONTEND_ROOT
# 1. Build (OBLIGATORIO)
npm run build
# ✅ Debe completar sin errores
# 2. Lint (OBLIGATORIO)
npm run lint
# ✅ Debe pasar o corregir errores
# 3. Type check
npm run typecheck # o tsc --noEmit
# ✅ Debe pasar
# 4. Iniciar aplicación
npm run dev
# ✅ Debe iniciar sin errores
```
**Criterios de éxito:**
```
✅ TypeScript compila sin errores
✅ ESLint sin errores críticos
✅ Aplicación renderiza correctamente
✅ Sin errores en consola del navegador
✅ Componentes funcionan según diseño
```
**Si falla:**
```
🛑 NO marcar como completada
1. Revisar errores de TypeScript/React
2. Corregir código
3. Re-ejecutar build + lint
4. Solo entonces continuar
```
---
## VALIDACIÓN DE COHERENCIA
### Coherencia Documentación ↔ Código
**Verificar:**
```markdown
- [ ] Lo implementado coincide con docs/
- [ ] No hay features documentadas sin implementar
- [ ] No hay código sin documentación correspondiente
- [ ] ADRs actualizados si hay decisiones nuevas
```
### Coherencia Entre Capas (3-Tier)
**Database ↔ Backend:**
```markdown
- [ ] Entity mapea correctamente a tabla
- [ ] Tipos de columnas coinciden
- [ ] Relaciones (FK) correctas
- [ ] Nombres de campos alineados
```
**Backend ↔ Frontend:**
```markdown
- [ ] DTOs coinciden con types del frontend
- [ ] Endpoints documentados en Swagger
- [ ] Respuestas API coinciden con interfaces FE
- [ ] Errores manejados consistentemente
```
### Anti-Duplicación
**Verificar después de crear:**
```bash
# Buscar objetos con nombre similar
grep -rn "{nombre}" @INVENTORY
# No debe haber entradas duplicadas
# Si hay duplicados → ERROR → Corregir
```
---
## MATRIZ DE VALIDACIONES POR TIPO DE TAREA
| Tipo de Tarea | Build | Lint | Tests | Carga Limpia | Coherencia 3-Tier |
|---------------|-------|------|-------|--------------|-------------------|
| Nueva tabla | - | - | - | ✅ OBLIGATORIO | ✅ |
| Nueva entity | ✅ BE | ✅ BE | ✅ BE | - | ✅ |
| Nuevo service | ✅ BE | ✅ BE | ✅ BE | - | - |
| Nuevo controller | ✅ BE | ✅ BE | ✅ BE | - | ✅ |
| Nuevo componente | ✅ FE | ✅ FE | ✅ FE | - | ✅ |
| Nueva página | ✅ FE | ✅ FE | ✅ FE | - | ✅ |
| Bug fix | ✅ Afectado | ✅ Afectado | ✅ Afectado | Si DDL | - |
| Refactor | ✅ TODO | ✅ TODO | ✅ TODO | Si DDL | ✅ |
---
## PROTOCOLO DE FALLA
### Si Build Falla
```markdown
## ❌ Build Fallido
**Error:**
{copiar error completo}
**Archivo(s) afectado(s):**
- {lista de archivos}
**Análisis:**
{descripción del problema}
**Acción:**
1. Corregir {archivo} línea {N}
2. Re-ejecutar build
3. Continuar solo si pasa
```
### Si Lint Falla (Errores Críticos)
```markdown
## ❌ Lint Fallido
**Errores críticos:**
{lista de errores}
**Acción:**
1. Corregir cada error
2. Re-ejecutar lint
3. Warnings son aceptables
4. Errores NO son aceptables
```
### Si Tests Fallan
```markdown
## ❌ Tests Fallidos
**Tests que fallan:**
- {test 1}: {razón}
- {test 2}: {razón}
**Acción:**
1. Analizar si es error de código o de test
2. Si error de código → Corregir código
3. Si test desactualizado → Actualizar test
4. Re-ejecutar tests
```
### Si Carga Limpia Falla
```markdown
## ❌ Carga Limpia Fallida
**Error:**
{error de PostgreSQL}
**Archivo DDL problemático:**
{archivo.sql}
**Acción:**
1. NO ejecutar fix manual en BD
2. Corregir archivo DDL
3. Re-ejecutar carga limpia completa
4. Repetir hasta éxito
```
---
## REPORTE DE VALIDACIÓN
**Incluir en cada entrega:**
```markdown
## Validaciones Ejecutadas
### Build
- Backend: ✅ Pasa | ❌ Falla
- Frontend: ✅ Pasa | ❌ Falla | ⏭️ N/A
### Lint
- Backend: ✅ Pasa | ❌ Falla
- Frontend: ✅ Pasa | ❌ Falla | ⏭️ N/A
### Tests
- Backend: ✅ Pasa | ❌ Falla | ⏭️ N/A
- Frontend: ✅ Pasa | ❌ Falla | ⏭️ N/A
### Carga Limpia (DDL)
- Database: ✅ Pasa | ❌ Falla | ⏭️ N/A
### Coherencia
- Docs ↔ Código: ✅ OK | ❌ Discrepancia
- DB ↔ BE: ✅ OK | ❌ Discrepancia | ⏭️ N/A
- BE ↔ FE: ✅ OK | ❌ Discrepancia | ⏭️ N/A
### Estado Final
✅ TODAS LAS VALIDACIONES PASAN → Tarea completable
❌ ALGUNA VALIDACIÓN FALLA → Tarea NO completable
```
---
## ERRORES COMUNES
| Error | Causa | Solución |
|-------|-------|----------|
| Reportar sin validar | Prisa por entregar | SIEMPRE ejecutar validaciones |
| Fix manual en BD | Carga limpia falla | Corregir DDL, no BD directamente |
| Ignorar warnings de lint | Parecer inofensivos | Revisar si son errores disfrazados |
| Saltar tests | "No hay tiempo" | Tests son OBLIGATORIOS |
| No verificar coherencia | Asumir que está bien | Verificar SIEMPRE entre capas |
---
## REFERENCIAS
- **Ciclo de vida de tareas:** @CAPVED (PRINCIPIO-CAPVED.md) - Fase V y E
- **Punto de entrada HU:** @TAREA (SIMCO-TAREA.md)
- **Crear archivos:** @CREAR (SIMCO-CREAR.md)
- **Documentar:** @DOCUMENTAR (SIMCO-DOCUMENTAR.md)
- **Directiva completa de validación:** @DIRECTIVAS/PROCESO-VALIDACION.md
---
**Versión:** 1.1.0 | **Sistema:** SIMCO + CAPVED | **Mantenido por:** Tech Lead

345
orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md Normal file
View File

@ -0,0 +1,345 @@
# TRIGGER-ANALISIS-DEPENDENCIAS
**ID:** TRIGGER-ANALISIS-DEPENDENCIAS
**Version:** 1.0.0
**Tipo:** Automatico
**Fase CAPVED:** Se activa en Fase A (Analisis)
---
## Proposito
Analizar automaticamente las dependencias de un archivo antes de modificarlo,
identificando tanto los archivos de los que depende (imports) como los archivos
que dependen de el (dependientes), para evaluar el impacto del cambio y
asegurar que todos los archivos afectados sean considerados en el plan.
---
## Cuando Se Activa
```yaml
activadores:
palabras_clave:
- "modificar"
- "cambiar"
- "actualizar"
- "refactorizar"
- "eliminar"
- "renombrar"
- "mover"
tipos_operacion:
- Modificacion de archivo existente
- Eliminacion de archivo
- Renombrado de archivo/clase/funcion
- Cambio de firma de funcion/metodo
- Cambio de estructura de tabla/entity
ejemplos:
- "Modificar UserEntity para agregar campo email_verified"
- "Cambiar estructura de tabla payments"
- "Refactorizar AuthService"
- "Renombrar componente Dashboard a AdminDashboard"
- "Eliminar funcion deprecada calculateTotal"
```
---
## Acciones del Trigger
### Paso 1: Identificar Dependencias (Imports)
```yaml
accion: "Identificar archivos que el archivo modificado importa"
descripcion: "Estos son los archivos de los que DEPENDE el archivo a modificar"
comandos:
typescript:
- grep -E "^import .* from" {archivo}
- grep -E "require\(" {archivo}
python:
- grep -E "^from .* import|^import " {archivo}
sql:
- grep -E "REFERENCES|FOREIGN KEY" {archivo}
output:
formato: |
## Dependencias (de los que depende)
| Archivo | Tipo de Dependencia |
|---------|---------------------|
| {ruta} | {import/extends/uses} |
```
### Paso 2: Identificar Dependientes
```yaml
accion: "Identificar archivos que importan o usan el archivo a modificar"
descripcion: "Estos son los archivos que DEPENDEN del archivo a modificar"
comandos:
buscar_imports:
- grep -rn "from.*{nombre_modulo}" apps/ libs/ src/
- grep -rn "import.*{NombreClase}" apps/ libs/ src/
- grep -rn "require.*{nombre}" apps/ libs/ src/
buscar_uso:
- grep -rn "{NombreClase}" apps/ libs/ src/ --include="*.ts"
- grep -rn "{nombre_funcion}\(" apps/ libs/ src/
buscar_referencias_bd:
- grep -rn "REFERENCES.*{tabla}" database/
- grep -rn "{tabla}\." apps/ libs/ src/
output:
formato: |
## Dependientes (los que dependen de este)
| Archivo | Linea | Tipo de Uso |
|---------|-------|-------------|
| {ruta} | {linea} | {import/call/extends} |
```
### Paso 3: Evaluar Impacto
```yaml
accion: "Clasificar el nivel de impacto del cambio"
clasificacion:
ALTO:
condiciones:
- Mas de 5 dependientes
- Cambio es breaking (firma, estructura, nombre)
- Afecta multiples capas (DB + BE + FE)
- Afecta modulo compartido
acciones:
- Listar TODOS los archivos afectados
- Incluir actualizacion de dependientes en plan
- Considerar migracion gradual
- Verificar tests existentes
MEDIO:
condiciones:
- 2-5 dependientes
- Cambio es aditivo (nuevo campo, nueva funcion)
- Afecta una capa principalmente
acciones:
- Listar archivos afectados
- Evaluar si dependientes necesitan cambios
- Actualizar tests si existen
BAJO:
condiciones:
- 0-1 dependientes
- Cambio interno (no afecta API publica)
- Refactoring sin cambio de comportamiento
acciones:
- Proceder con precaucion normal
- Verificar build y lint
```
### Paso 4: Generar Plan de Modificacion
```yaml
accion: "Proponer orden de modificacion basado en dependencias"
reglas_orden:
1. Modificar dependencias primero (lo que importa)
2. Modificar archivo principal
3. Modificar dependientes (los que importan)
4. Actualizar tests
5. Validar build completo
ejemplo:
si_modifica: "UserEntity"
orden_sugerido:
1. user.entity.ts (archivo principal)
2. user.service.ts (usa UserEntity)
3. user.controller.ts (usa UserService)
4. user.dto.ts (si hay cambios de estructura)
5. user.spec.ts (tests)
6. components usando user (frontend)
```
---
## Formato de Reporte
```markdown
## Analisis de Dependencias
### Archivo a Modificar
- Ruta: {ruta_completa}
- Tipo: {entity|service|component|table|...}
- Proyecto: {proyecto}
### Tipo de Cambio
- Descripcion: {que se va a cambiar}
- Breaking: {SI | NO}
- Afecta API Publica: {SI | NO}
### Dependencias (de los que depende)
| # | Archivo | Tipo |
|---|---------|------|
| 1 | {ruta} | {import/extends} |
### Dependientes (los que dependen de este)
| # | Archivo | Linea | Tipo de Uso | Requiere Cambio |
|---|---------|-------|-------------|-----------------|
| 1 | {ruta} | {n} | {import} | {SI/NO/EVALUAR} |
### Clasificacion de Impacto
**Nivel: {ALTO | MEDIO | BAJO}**
Razon: {explicacion}
### Plan de Modificacion Sugerido
1. {paso_1}
2. {paso_2}
...
### Archivos a Incluir en el Plan
- [ ] {archivo_1}
- [ ] {archivo_2}
...
### Advertencias
{lista_de_advertencias_si_aplica}
```
---
## Casos Especiales
### Cambio en Entity de Base de Datos
```yaml
si_modifica: "*.entity.ts"
buscar_adicional:
- Archivo de migracion relacionado
- DTOs que exponen la entity
- Services que usan la entity
- Controllers que exponen endpoints
- Componentes frontend que muestran datos
verificar:
- Coherencia con esquema DDL
- Migracion necesaria si es produccion
- Validaciones en DTOs
```
### Cambio en Tabla DDL
```yaml
si_modifica: "*.sql (CREATE TABLE, ALTER TABLE)"
buscar_adicional:
- Entity correspondiente en backend
- Otras tablas con FOREIGN KEY
- Vistas que usan la tabla
- Funciones/triggers que referencian
verificar:
- Script recreate-database.sh actualizado
- Migracion para produccion
- Seed data si aplica
```
### Cambio en Servicio Compartido
```yaml
si_modifica: "shared/modules/*.ts"
buscar_adicional:
- Todos los proyectos que importan el modulo
- Proyectos en projects/ que usan shared/
alerta: |
ATENCION: Cambio en modulo compartido.
Este cambio puede afectar multiples proyectos.
Considerar:
1. Versionado del modulo
2. Cambio backward-compatible si es posible
3. Propagacion coordinada a proyectos
```
---
## Ejemplos de Ejecucion
### Ejemplo 1: Modificar Entity
```
Usuario: Modificar UserEntity para agregar campo email_verified
Sistema:
== TRIGGER-ANALISIS-DEPENDENCIAS ACTIVADO ==
### Archivo a Modificar
- Ruta: apps/api/src/modules/users/entities/user.entity.ts
- Tipo: Entity
### Dependencias
| Archivo | Tipo |
|---------|------|
| typeorm | import |
| base.entity.ts | extends |
### Dependientes (12 encontrados)
| Archivo | Linea | Tipo | Requiere Cambio |
|---------|-------|------|-----------------|
| user.service.ts | 5 | import | EVALUAR |
| user.controller.ts | 8 | import | NO |
| auth.service.ts | 12 | import | NO |
| create-user.dto.ts | 3 | reference | SI |
| update-user.dto.ts | 3 | reference | SI |
| user.spec.ts | 10 | import | SI |
... (6 mas)
### Impacto: ALTO (>5 dependientes, cambio de estructura)
### Plan Sugerido
1. Actualizar user.entity.ts (agregar campo)
2. Actualizar create-user.dto.ts (agregar campo opcional)
3. Actualizar update-user.dto.ts (agregar campo)
4. Actualizar user.spec.ts (agregar tests)
5. Verificar migracion de BD necesaria
6. Build + lint + test
```
### Ejemplo 2: Cambio Bajo Impacto
```
Usuario: Refactorizar metodo interno en PaymentService
Sistema:
== TRIGGER-ANALISIS-DEPENDENCIAS ACTIVADO ==
### Archivo a Modificar
- Ruta: apps/api/src/modules/payments/payment.service.ts
- Tipo: Service
### Dependientes (2 encontrados)
| Archivo | Tipo | Requiere Cambio |
|---------|------|-----------------|
| payment.controller.ts | import | NO (metodo interno) |
| payment.spec.ts | import | EVALUAR (tests) |
### Impacto: BAJO (metodo interno, no afecta API publica)
### Plan Sugerido
1. Refactorizar metodo en payment.service.ts
2. Actualizar tests si cambia comportamiento
3. Build + lint
```
---
## Integracion con Modos
### En MODE-FULL
- Se ejecuta siempre en Fase A
- Resultado incluido en plan de Fase P
### En MODE-QUICK
- NO se ejecuta (cambios menores no requieren)
- Si build falla, escalar a MODE-FULL
### En MODE-ANALYSIS
- Se ejecuta para generar reporte de impacto
- No se incluye plan de ejecucion
---
*TRIGGER-ANALISIS-DEPENDENCIAS v1.0.0 - Sistema SAAD*

282
orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md Normal file
View File

@ -0,0 +1,282 @@
# TRIGGER-ANTI-DUPLICACION
**ID:** TRIGGER-ANTI-DUPLICACION
**Version:** 1.0.0
**Tipo:** Automatico
**Fase CAPVED:** Se activa en Fase A (Analisis)
---
## Proposito
Prevenir la creacion de objetos duplicados verificando automaticamente el
catalogo global y los inventarios del proyecto antes de crear cualquier
archivo, componente, servicio, entidad o tabla nueva.
---
## Cuando Se Activa
```yaml
activadores:
palabras_clave:
- "crear"
- "nuevo"
- "agregar"
- "implementar"
- "anadir"
- "generar"
tipos_objeto:
- tabla (DDL)
- entity
- service
- controller
- componente
- hook
- modulo
- funcionalidad
ejemplos:
- "Crear nueva tabla de usuarios"
- "Agregar entidad PaymentMethod"
- "Implementar servicio de notificaciones"
- "Nuevo componente de dashboard"
```
---
## Acciones del Trigger
### Paso 1: Verificar Catalogo Global
```yaml
accion: "Buscar en catalogo de funcionalidades reutilizables"
comando: |
grep -i "{funcionalidad}" shared/catalog/CATALOG-INDEX.yml
catalogo_contiene:
- auth (autenticacion y autorizacion)
- session-management (gestion de sesiones)
- rate-limiting (limitacion de tasa)
- notifications (notificaciones email/push)
- multi-tenancy (soporte multi-tenant)
- feature-flags (flags dinamicos)
- websocket (comunicacion tiempo real)
- payments (integracion pagos)
- audit-logs (auditoria)
- portales (templates de portales)
- template-saas (template SaaS completo)
si_existe_en_catalogo:
accion: "DETENER creacion"
mensaje: |
ATENCION: Esta funcionalidad ya existe en el catalogo global.
Ubicacion: shared/catalog/{funcionalidad}/
Documentacion: shared/catalog/{funcionalidad}/README.md
Recomendacion: Usar SIMCO-REUTILIZAR.md para integrar
el modulo existente en lugar de crear uno nuevo.
Si necesita modificaciones, considerar:
1. Extender el modulo existente
2. Contribuir mejoras al catalogo
Para continuar de todos modos, confirmar explicitamente.
```
### Paso 2: Verificar Inventario del Proyecto
```yaml
accion: "Buscar en inventarios del proyecto actual"
comandos:
- grep -i "{nombre}" orchestration/inventarios/MASTER_INVENTORY.yml
- grep -i "{nombre}" orchestration/inventarios/DATABASE_INVENTORY.yml
- grep -i "{nombre}" orchestration/inventarios/BACKEND_INVENTORY.yml
- grep -i "{nombre}" orchestration/inventarios/FRONTEND_INVENTORY.yml
si_existe_en_inventario:
accion: "DETENER creacion"
mensaje: |
ATENCION: Ya existe un objeto similar en este proyecto.
Nombre: {nombre_existente}
Tipo: {tipo}
Ubicacion: {ruta}
Opciones:
1. Reutilizar el existente
2. Extender el existente
3. Renombrar el nuevo si es diferente
Para continuar, clarificar la diferencia.
```
### Paso 3: Buscar Archivos Similares
```yaml
accion: "Buscar archivos con nombre similar en el codigo"
comandos:
- find apps/ libs/ -name "*{nombre}*" -type f
- find src/ -name "*{nombre}*" -type f
- grep -rn "class {Nombre}" apps/ libs/ src/
- grep -rn "interface {Nombre}" apps/ libs/ src/
- grep -rn "CREATE TABLE.*{nombre}" database/
si_encuentra_similar:
accion: "ALERTAR y preguntar"
mensaje: |
ATENCION: Se encontraron archivos similares:
{lista_archivos}
Por favor confirmar:
1. Es el mismo objeto? -> Usar el existente
2. Es diferente? -> Explicar la diferencia
3. Es un duplicado a consolidar? -> Usar @DELETE-SAFE primero
```
### Paso 4: Evaluar Resultado
```yaml
matriz_decision:
existe_en_catalogo:
accion: "REUTILIZAR del catalogo"
simco: "SIMCO-REUTILIZAR.md"
no_encontrado:
accion: "PROCEDER a crear"
simco: "SIMCO-CREAR.md"
existe_identico:
accion: "DETENER"
mensaje: "Ya existe, no crear duplicado"
existe_similar:
accion: "PREGUNTAR"
mensaje: "Clarificar diferencia antes de continuar"
```
---
## Checklist Rapido Anti-Duplicacion
Antes de crear cualquier objeto nuevo, verificar:
```markdown
[ ] Busque funcionalidad en shared/catalog/CATALOG-INDEX.yml
[ ] Busque "{nombre}" en orchestration/inventarios/
[ ] Busque archivos con find en apps/ y src/
[ ] Busque definiciones con grep (class, interface, CREATE TABLE)
[ ] Confirme que NO existe en catalogo NI en proyecto
[ ] Si existe en catalogo, use SIMCO-REUTILIZAR.md
[ ] Si existe similar, pregunte que hacer antes de continuar
```
---
## Formato de Reporte
Cuando se activa este trigger, generar reporte:
```markdown
## Verificacion Anti-Duplicacion
### Objeto a Crear
- Nombre: {nombre}
- Tipo: {tabla|entity|service|component|...}
- Proyecto: {proyecto}
### Resultado Catalogo Global
- Estado: {ENCONTRADO | NO_ENCONTRADO}
- Detalles: {ubicacion si encontrado}
### Resultado Inventario Proyecto
- Estado: {ENCONTRADO | NO_ENCONTRADO}
- Detalles: {nombre y ubicacion si encontrado}
### Resultado Busqueda Codigo
- Estado: {ENCONTRADO | NO_ENCONTRADO}
- Archivos similares: {lista si encontrados}
### Decision
- [ ] PROCEDER: No se encontraron duplicados
- [ ] REUTILIZAR: Usar modulo del catalogo
- [ ] DETENER: Ya existe en proyecto
- [ ] CONSULTAR: Existe similar, clarificar
```
---
## Excepciones
### Cuando NO aplicar este trigger
```yaml
excepciones:
- Archivos de configuracion (no son objetos reutilizables)
- Tests (cada modulo tiene sus propios tests)
- Documentacion (puede haber docs similares)
- Migraciones de BD (tienen timestamp unico)
```
---
## Integracion con SIMCO
### Si se encuentra en catalogo
```yaml
siguiente_paso: "Leer SIMCO-REUTILIZAR.md"
acciones:
1. Leer documentacion del modulo en catalogo
2. Verificar compatibilidad con proyecto
3. Seguir instrucciones de integracion
4. Registrar uso en inventario
```
### Si no se encuentra
```yaml
siguiente_paso: "Leer SIMCO-CREAR.md"
acciones:
1. Proceder con creacion normal
2. Seguir principio Doc-Primero
3. Registrar en inventario al crear
4. Evaluar si debe agregarse al catalogo
```
---
## Ejemplo de Ejecucion
```
Usuario: Crear servicio de autenticacion para erp-construccion
Sistema:
== TRIGGER-ANTI-DUPLICACION ACTIVADO ==
Paso 1: Verificando catalogo global...
Buscando: "auth" en shared/catalog/CATALOG-INDEX.yml
ENCONTRADO: shared/catalog/auth/
Paso 2: Verificando inventario...
(No aplica - se encontro en catalogo)
Paso 3: Busqueda codigo...
(No aplica - se encontro en catalogo)
== RESULTADO ==
DETENIDO: Funcionalidad existe en catalogo global.
Ubicacion: shared/catalog/auth/
Contenido:
- NestJS + JWT + Passport
- Guards, strategies, decorators
- Documentacion completa
Recomendacion:
Usar SIMCO-REUTILIZAR.md para integrar el modulo
de autenticacion del catalogo.
Comando sugerido:
@CREATE-SAFE Integrar modulo auth del catalogo en erp-construccion
```
---
*TRIGGER-ANTI-DUPLICACION v1.0.0 - Sistema SAAD*

267
orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md Normal file
View File

@ -0,0 +1,267 @@
# TRIGGER: CIERRE DE TAREA OBLIGATORIO
**Versión:** 1.0.0
**Fecha:** 2026-01-16
**Sistema:** SIMCO v4.0.0
**Alias:** @TRIGGER_CIERRE
---
## RESUMEN EJECUTIVO
Este trigger OBLIGA la ejecución del checklist post-tarea (@DEF_CHK_POST) antes de que cualquier tarea pueda ser marcada como completada.
**PRINCIPIO:** "Una tarea no está completada hasta que su checklist de cierre esté 100% verificado."
---
## CONDICIONES DE ACTIVACIÓN
```yaml
activar_cuando:
- Agente intenta marcar tarea como "completada"
- Agente dice "tarea finalizada" o variantes
- Agente termina la última subtarea del plan
- Agente declara "Done" o "DONE"
- Agente reporta que terminó el trabajo
palabras_clave_trigger:
- "completada"
- "finalizada"
- "terminada"
- "Done"
- "DONE"
- "tarea cerrada"
- "trabajo terminado"
- "implementación completa"
```
---
## ACCIÓN REQUERIDA
### Secuencia Obligatoria
```
AGENTE DECLARA TAREA TERMINADA
│
▼
┌─────────────────────────────────────┐
│ 1. DETENER │
│ No marcar como completada aún │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 2. CARGAR @DEF_CHK_POST │
│ CHECKLIST-POST-TASK.md │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 3. EJECUTAR CHECKLIST │
│ - Gobernanza (BLOQUEANTE) │
│ - Validaciones técnicas │
│ - Coherencia entre capas │
│ - Inventarios │
│ - Trazas │
│ - Propagación │
└─────────────────┬───────────────────┘
│
▼
┌───────────────┐
│ ¿TODOS PASAN? │
└───────┬───────┘
/ \
Sí No
│ │
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ 4. MARCAR │ │ 4. MANTENER EN │
│ COMPLETADA │ │ PROGRESO │
└──────────────┘ │ │
│ - Documentar items │
│ faltantes │
│ - Completar antes │
│ de cerrar │
└──────────────────────┘
```
---
## CHECKLIST RÁPIDO DE CIERRE
```markdown
## Verificación Pre-Cierre (@DEF_CHK_POST)
### 0. Gobernanza (BLOQUEANTE - SI FALLA, NO CONTINUAR)
[ ] Carpeta de tarea existe: orchestration/tareas/TASK-{ID}/
[ ] METADATA.yml completo con fases C, E, D
[ ] _INDEX.yml de tareas actualizado
### 1. Validaciones Técnicas
[ ] Build pasa (backend y/o frontend según aplique)
[ ] Lint pasa
[ ] Tests pasan (si existen)
### 2. Coherencia Entre Capas
[ ] DDL ↔ Backend coherente (o excepciones documentadas)
[ ] Backend ↔ Frontend coherente (si aplica)
### 3. Inventarios Actualizados
[ ] DATABASE_INVENTORY.yml (si cambió BD)
[ ] BACKEND_INVENTORY.yml (si cambió BE)
[ ] FRONTEND_INVENTORY.yml (si cambió FE)
[ ] MASTER_INVENTORY.yml (siempre)
### 4. Trazas Actualizadas
[ ] Traza de tarea correspondiente actualizada
[ ] PROXIMA-ACCION.md actualizado
### 5. Propagación Evaluada
[ ] ¿Cambio debe propagarse a otros proyectos? (evaluar)
[ ] Si aplica: propagación ejecutada o documentada como pendiente
```
---
## BLOQUEO
### SI el checklist NO pasa:
```yaml
accion: "BLOQUEAR cierre de tarea"
estado: "EN PROGRESO"
mensaje: |
Tarea NO puede ser marcada como completada.
Items faltantes del checklist:
- [listar items que fallaron]
Acción requerida:
- Completar items faltantes
- Re-ejecutar checklist
- Solo entonces marcar como completada
reintentar: "Después de completar items faltantes"
```
### Items BLOQUEANTES (no negociables):
```yaml
bloqueantes_absolutos:
- Gobernanza (carpeta + METADATA + _INDEX)
- Build que falla
- Tests que fallan
advertencias_serias:
- Inventarios desactualizados
- Trazas desactualizadas
- Coherencia no verificada
advertencias_menores:
- Propagación no evaluada (si proyecto aislado)
```
---
## INTEGRACIÓN CON OTROS TRIGGERS
```yaml
secuencia_de_triggers:
1: "Agente ejecuta trabajo"
2: "Agente intenta cerrar tarea"
3: "→ TRIGGER-CIERRE-TAREA-OBLIGATORIO se activa"
4: "→ Carga @DEF_CHK_POST"
5: "→ TRIGGER-INVENTARIOS-SINCRONIZADOS verifica inventarios"
6: "→ TRIGGER-COHERENCIA-CAPAS verifica coherencia"
7: "→ TRIGGER-DOCUMENTACION-OBLIGATORIA verifica gobernanza"
8: "Si todo pasa: tarea = COMPLETADA"
9: "Si algo falla: tarea = EN PROGRESO"
dependencias:
- "@TRIGGER_INVENTARIOS"
- "@TRIGGER_COHERENCIA"
- "@TRIGGER_DOC"
```
---
## MENSAJES ESTÁNDAR
### Al detectar intento de cierre:
```
⚠️ TRIGGER-CIERRE-TAREA-OBLIGATORIO activado
Antes de marcar la tarea como completada, debo ejecutar el checklist post-tarea.
Ejecutando @DEF_CHK_POST...
```
### Si todo pasa:
```
✅ Checklist post-tarea completado exitosamente
Verificaciones:
- [✓] Gobernanza
- [✓] Validaciones técnicas
- [✓] Coherencia entre capas
- [✓] Inventarios sincronizados
- [✓] Trazas actualizadas
- [✓] Propagación evaluada
TAREA MARCADA COMO COMPLETADA
```
### Si algo falla:
```
❌ Checklist post-tarea NO completado
Items faltantes:
- [ ] {item que falló}
- [ ] {otro item que falló}
Acción: Completar items faltantes antes de cerrar.
Estado: EN PROGRESO (no completada)
```
---
## EXCEPCIONES
```yaml
excepciones_permitidas:
tareas_triviales:
- Corrección de typos
- Actualización de comentarios
- Cambios cosméticos
checklist_reducido:
- Solo Gobernanza
- Solo Validación build
investigación_pura:
- Análisis sin cambios de código
- Spikes exploratorios
checklist_reducido:
- Solo documentación de hallazgos
nota: "Incluso excepciones DEBEN documentar en trazas"
```
---
## REFERENCIAS
| Alias | Archivo |
|-------|---------|
| @DEF_CHK_POST | orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md |
| @TRIGGER_INVENTARIOS | orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md |
| @TRIGGER_COHERENCIA | orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md |
| @TRIGGER_DOC | orchestration/directivas/triggers/TRIGGER-DOCUMENTACION-OBLIGATORIA.md |
| @CAPVED | orchestration/directivas/principios/PRINCIPIO-CAPVED.md |
---
**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Trigger de Cierre Obligatorio

311
orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md Normal file
View File

@ -0,0 +1,311 @@
# TRIGGER: COHERENCIA ENTRE CAPAS
**Versión:** 1.0.0
**Fecha:** 2026-01-16
**Sistema:** SIMCO v4.0.0
**Alias:** @TRIGGER_COHERENCIA
---
## RESUMEN EJECUTIVO
Este trigger OBLIGA a mantener coherencia entre las capas DDL, Backend y Frontend. Se activa automáticamente cuando se crea o modifica cualquier objeto en cualquier capa.
**PRINCIPIO:** "Ninguna capa puede tener objetos huérfanos. Todo DDL debe tener entity, todo entity que requiera persistencia debe tener DDL."
---
## CONDICIONES DE ACTIVACIÓN
```yaml
activar_cuando:
DDL:
- Se crea nueva tabla (CREATE TABLE)
- Se modifica estructura de tabla (ALTER TABLE)
- Se crea nuevo schema
- Se elimina tabla o schema
Backend:
- Se crea nueva entity
- Se modifica entity existente
- Se crea nuevo módulo
- Se elimina entity o módulo
Frontend:
- Se crea componente que consume endpoint nuevo
- Se crea store/hook que requiere datos de API
```
---
## VERIFICACIONES OBLIGATORIAS
### 1. Al Crear Tabla DDL
```yaml
ANTES_de_completar_tarea:
verificar:
- "¿Existe entity correspondiente en backend?"
- "¿Entity tiene mismos campos que tabla?"
- "¿Tipos de datos son compatibles (PostgreSQL ↔ TypeScript)?"
- "¿Está documentada en DATABASE_INVENTORY.yml?"
- "¿Está documentada en ENTITIES-CATALOG.md?"
si_no_existe_entity:
accion: "BLOQUEAR hasta crear entity"
excepcion: "Tablas de relación M:N pueden no tener entity si están documentadas como tal"
si_no_documentada:
accion: "BLOQUEAR hasta documentar en inventarios"
```
### 2. Al Crear Entity
```yaml
ANTES_de_completar_tarea:
verificar:
- "¿Existe tabla DDL correspondiente?"
- "¿Campos coinciden con DDL?"
- "¿Decoradores TypeORM son correctos?"
- "¿Está documentada en BACKEND_INVENTORY.yml?"
- "¿Está documentada en ENTITIES-CATALOG.md?"
si_no_existe_tabla:
accion: "BLOQUEAR hasta crear tabla DDL"
excepcion: "Entities de solo lectura (views) deben estar documentadas"
si_no_documentada:
accion: "BLOQUEAR hasta documentar en inventarios"
```
### 3. Al Crear Módulo Backend
```yaml
ANTES_de_completar_tarea:
verificar:
- "¿Todas las entities del módulo tienen tabla DDL?"
- "¿Módulo está documentado en MODULES-CATALOG.md?"
- "¿Servicios están documentados en SERVICES-CATALOG.md?"
- "¿Endpoints están documentados en QUICK-API.yml?"
si_incompleto:
accion: "BLOQUEAR hasta completar documentación"
```
### 4. Al Crear Schema DDL
```yaml
ANTES_de_completar_tarea:
verificar:
- "¿Schema tiene al menos un módulo backend correspondiente?"
- "¿Schema está documentado en DATABASE-SCHEMA.md?"
- "¿Schema está en DATABASE_INVENTORY.yml?"
si_schema_vacio:
accion: "ADVERTIR - Schema sin tablas debe tener plan de uso"
si_no_documentado:
accion: "BLOQUEAR hasta documentar"
```
---
## MATRIZ DE COHERENCIA
```
┌─────────────────────────────────────────────────────────────────┐
│ MATRIZ DE COHERENCIA │
├─────────────────────────────────────────────────────────────────┤
│ │
│ DDL (Schema/Tabla) │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Tabla │────▶│ Entity │────▶│ Service │ │
│ │ DDL │ │ TypeORM │ │ NestJS │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ DATABASE_ │ │ BACKEND_ │ │ QUICK- │ │
│ │ INVENTORY │ │ INVENTORY │ │ API.yml │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ ENTITIES-CATALOG│ │
│ │ MODULES-CATALOG │ │
│ │ SERVICES-CATALOG│ │
│ └─────────────────┘ │
│ │
│ REGLA: Cada flecha representa una DEPENDENCIA OBLIGATORIA │
│ No puede existir ningún nodo sin sus dependencias │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## EXCEPCIONES PERMITIDAS
```yaml
excepciones:
tablas_sin_entity:
- tipo: "Tablas de relación M:N gestionadas por TypeORM"
requisito: "Documentar en ENTITIES-CATALOG.md sección 'Relaciones'"
ejemplo: "user_roles, permission_roles"
- tipo: "Tablas de auditoría automática"
requisito: "Documentar en DATABASE-SCHEMA.md sección 'Audit'"
ejemplo: "audit_logs, activity_logs"
- tipo: "Tablas de sistema/migración"
requisito: "Documentar en DATABASE-SCHEMA.md sección 'System'"
ejemplo: "migrations, typeorm_metadata"
entities_sin_tabla:
- tipo: "View entities (solo lectura)"
requisito: "Documentar como @ViewEntity con query"
ejemplo: "UserStatsView, DashboardSummaryView"
- tipo: "Entities embebidas"
requisito: "Documentar como @Embeddable"
ejemplo: "AddressEmbed, MetadataEmbed"
schemas_sin_modulo:
- tipo: "Schemas planificados (FUTURE)"
requisito: "Documentar en DATABASE_INVENTORY con estado='PLANNED'"
requisito_2: "Crear issue/ticket de implementación"
```
---
## FLUJO DE VALIDACIÓN
```
┌─────────────────────────────────────────────────────────────────┐
│ FLUJO DE VALIDACIÓN │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Agente completa tarea │
│ │ │
│ ▼ │
│ 2. TRIGGER-COHERENCIA-CAPAS se activa │
│ │ │
│ ▼ │
│ 3. Detectar tipo de cambio (DDL/BE/FE) │
│ │ │
│ ▼ │
│ 4. Ejecutar verificaciones según tipo │
│ │ │
│ ├──── SI PASA ────▶ 5a. Permitir completar tarea │
│ │ │
│ └──── SI FALLA ───▶ 5b. BLOQUEAR y reportar gaps │
│ │ │
│ ▼ │
│ 6. Agente debe: │
│ - Crear objetos faltantes │
│ - Documentar en inventarios │
│ - Re-ejecutar validación │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## CHECKLIST DE COHERENCIA
### Para Cambios DDL
```markdown
[ ] Tabla tiene entity correspondiente en backend
[ ] Campos de entity coinciden con columnas de tabla
[ ] Tipos de datos son compatibles
[ ] Tabla documentada en DATABASE_INVENTORY.yml
[ ] Schema documentado en DATABASE-SCHEMA.md
[ ] Entity documentada en ENTITIES-CATALOG.md
```
### Para Cambios Backend
```markdown
[ ] Entity tiene tabla DDL correspondiente
[ ] Campos coinciden con DDL
[ ] Módulo documentado en MODULES-CATALOG.md
[ ] Servicios documentados en SERVICES-CATALOG.md
[ ] Entity documentada en BACKEND_INVENTORY.yml
[ ] Endpoints documentados en QUICK-API.yml
```
### Para Nuevo Schema
```markdown
[ ] Schema tiene módulo backend planificado o existente
[ ] Schema documentado en DATABASE-SCHEMA.md
[ ] Schema en DATABASE_INVENTORY.yml
[ ] Si no tiene módulo: documentar como PLANNED con fecha estimada
```
---
## INTEGRACIÓN CON OTROS TRIGGERS
```yaml
secuencia_triggers:
1: "TRIGGER-ANTI-DUPLICACION" # Verificar no existe
2: "TRIGGER-ANALISIS-DEPENDENCIAS" # Mapear impacto
3: "TRIGGER-COHERENCIA-CAPAS" # ← ESTE TRIGGER
4: "TRIGGER-DOCUMENTACION-OBLIGATORIA" # Documentar
orden: "TRIGGER-COHERENCIA-CAPAS se ejecuta ANTES de TRIGGER-DOC"
razon: "No se puede documentar algo que no está coherente"
```
---
## MENSAJES DE ERROR
```yaml
errores:
E-COH-001:
mensaje: "Tabla DDL sin entity correspondiente"
accion: "Crear entity antes de completar tarea"
bloqueante: true
E-COH-002:
mensaje: "Entity sin tabla DDL"
accion: "Crear tabla DDL o documentar como excepción"
bloqueante: true
E-COH-003:
mensaje: "Schema sin módulo backend"
accion: "Crear módulo o documentar como PLANNED"
bloqueante: true
E-COH-004:
mensaje: "Objeto no documentado en inventario"
accion: "Actualizar inventario correspondiente"
bloqueante: true
E-COH-005:
mensaje: "Discrepancia de campos DDL ↔ Entity"
accion: "Sincronizar campos entre DDL y Entity"
bloqueante: true
```
---
## REFERENCIAS
| Alias | Descripción |
|-------|-------------|
| @TRIGGER_COHERENCIA | Este trigger |
| @DEF_CHK_POST | Checklist post-tarea |
| @TRIGGER-DOC | Documentación obligatoria |
| @SIMCO-VALIDAR | Directiva de validación |
---
**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Trigger Preventivo

151
orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md Normal file
View File

@ -0,0 +1,151 @@
# TRIGGER: Commit y Push Obligatorio
**Version:** 1.0.0
**Fecha:** 2026-01-16
**Tipo:** AUTOMATICO
**Prioridad:** CRITICA
---
## ACTIVACION
Este trigger se activa AUTOMATICAMENTE cuando:
1. Se completa una tarea que creo o modifico archivos
2. Se marca un todo como "completed"
3. Se reporta al usuario que una tarea esta finalizada
4. Se cambia de contexto a otra tarea
5. Antes de finalizar una sesion de trabajo
---
## ACCION OBLIGATORIA
```
╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ ANTES DE REPORTAR TAREA COMPLETADA: ║
║ ║
║ 1. Ejecutar: git status ║
║ - Si hay cambios pendientes -> continuar ║
║ - Si esta limpio -> verificar que push se hizo ║
║ ║
║ 2. Si hay cambios: ║
║ git add . ║
║ git commit -m "[TAREA-ID] tipo: descripcion" ║
║ git push origin main ║
║ ║
║ 3. Si hay SUBMODULES modificados: ║
║ - Commitear y push en CADA submodule primero ║
║ - Luego actualizar workspace principal ║
║ ║
║ 4. Verificar sincronizacion: ║
║ git log origin/main..HEAD --oneline ║
║ - Debe estar VACIO (sin commits pendientes de push) ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
```
---
## SECUENCIA WORKSPACE-V2
El workspace-v2 usa submodules. Secuencia obligatoria:
```bash
# PASO 1: Identificar submodules modificados
cd /home/isem/workspace-v2
git status
# PASO 2: Para CADA submodule con cambios
cd projects/{submodule}
git add .
git commit -m "[{submodule}] tipo: descripcion"
git push origin main
cd ../..
# PASO 3: Actualizar workspace principal
git add .
git commit -m "[WORKSPACE] chore: descripcion de cambios"
git push origin main
# PASO 4: Verificar TODO sincronizado
git status # Debe mostrar "clean"
git submodule foreach 'git status' # Todos deben estar "clean"
```
---
## ERRORES A EVITAR
| Error | Consecuencia | Prevencion |
|-------|--------------|------------|
| No hacer push | Archivos solo en local | Siempre push despues de commit |
| Olvidar submodules | Referencias desincronizadas | Commitear submodules primero |
| Reportar sin verificar | Usuario cree que esta hecho | Verificar git status antes |
| Commitear sin push | Cambios no en remoto | Push inmediato tras commit |
---
## VERIFICACION RAPIDA
```bash
# Comando unico para verificar todo sincronizado
git status && git log origin/main..HEAD --oneline
# Salida esperada:
# On branch main
# Your branch is up to date with 'origin/main'.
# nothing to commit, working tree clean
# (sin output del log = todo pusheado)
```
---
## INTEGRACION CON CAPVED
Este trigger se ejecuta en:
- **Fase E (Ejecucion):** Commit atomico por cada cambio logico
- **Fase D (Documentacion):** Commit final con documentacion
- **Post-Tarea:** Push OBLIGATORIO antes de reportar completado
```yaml
fase_D_documentacion:
ultimo_paso: "Commit + Push de todos los cambios"
verificacion: "git status clean + git log empty"
reportar_solo_si: "Todo sincronizado con remoto"
```
---
## MENSAJE AL AGENTE
```
╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ RECUERDA: Una tarea NO esta completa hasta que: ║
║ ║
║ 1. Todos los archivos estan GUARDADOS en disco ║
║ 2. Todos los cambios estan COMMITEADOS ║
║ 3. Todos los commits estan PUSHEADOS al remoto ║
║ 4. git status muestra "working tree clean" ║
║ 5. git log origin/main..HEAD esta VACIO ║
║ ║
║ SIN PUSH = TRABAJO PERDIDO POTENCIAL ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
```
---
## REFERENCIAS
- SIMCO-GIT.md - Directiva principal de control de versiones
- PRINCIPIO-CAPVED.md - Ciclo de vida de tareas
- SIMCO-TAREA.md - Punto de entrada de tareas
---
**Sistema:** SIMCO v4.0.0
**Mantenido por:** Workspace Admin

178
orchestration/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md Normal file
View File

@ -0,0 +1,178 @@
# TRIGGER: Fetch Obligatorio Antes de Operar
**Version:** 1.0.0
**Fecha:** 2026-01-16
**Tipo:** AUTOMATICO
**Prioridad:** CRITICA
**Incidente de Origen:** INC-2026-01-16-001
---
## ACTIVACION
Este trigger se activa AUTOMATICAMENTE cuando:
1. Se inicia una sesion de trabajo en el workspace
2. Se va a verificar el estado de git (git status)
3. Se va a realizar cualquier operacion git (commit, push, pull)
4. Se retoma trabajo despues de una pausa
5. Se cambia de contexto entre proyectos/submodulos
---
## ACCION OBLIGATORIA
```
╔══════════════════════════════════════════════════════════════════════════╗
║ ║
║ ANTES DE VERIFICAR ESTADO O REALIZAR OPERACIONES GIT: ║
║ ║
║ 1. Ejecutar: git fetch origin ║
║ → Obtiene el estado actual del repositorio remoto ║
║ ║
║ 2. Verificar: git log HEAD..origin/main --oneline ║
║ → Si hay output = HAY COMMITS REMOTOS QUE NO TIENES ║
║ → Si esta vacio = Estas sincronizado ║
║ ║
║ 3. Si hay commits remotos: ║
║ git pull --no-recurse-submodules ║
║ → Sincroniza tu local con el remoto ║
║ ║
║ 4. AHORA SI verificar estado: ║
║ git status ║
║ ║
║ MOTIVO: Otro agente pudo haber hecho cambios en otra sesion. ║
║ Sin FETCH, reportaras estado incompleto. ║
║ ║
╚══════════════════════════════════════════════════════════════════════════╝
```
---
## SECUENCIA COMPLETA
```bash
# PASO 1: Fetch del remoto
git fetch origin
# PASO 2: Verificar si hay commits remotos no sincronizados
REMOTE_COMMITS=$(git log HEAD..origin/main --oneline)
# PASO 3: Si hay commits remotos, sincronizar
if [ -n "$REMOTE_COMMITS" ]; then
echo "Commits remotos detectados:"
echo "$REMOTE_COMMITS"
git pull --no-recurse-submodules
fi
# PASO 4: Ahora verificar estado local
git status
```
---
## PARA WORKSPACE CON SUBMODULOS
En workspace-v2 con multiples niveles de submodulos:
```bash
# NIVEL 0: Workspace principal
cd /home/isem/workspace-v2
git fetch origin
git log HEAD..origin/main --oneline
# Si hay output: git pull --no-recurse-submodules
git status
# NIVEL 1: Proyectos (si vas a trabajar en uno)
cd projects/{proyecto}
git fetch origin
git log HEAD..origin/main --oneline
# Si hay output: git pull --no-recurse-submodules
git status
# NIVEL 2: Subrepositorios (si vas a trabajar en uno)
cd {componente} # backend, database, frontend
git fetch origin
git log HEAD..origin/main --oneline
# Si hay output: git pull --no-recurse-submodules
git status
```
---
## ERRORES A EVITAR
| Error | Consecuencia | Prevencion |
|-------|--------------|------------|
| Solo hacer git status | No detectar commits remotos | SIEMPRE fetch primero |
| Reportar "clean" sin fetch | Usuario confundido | Seguir secuencia completa |
| Asumir que no hay cambios | Desincronizacion | Verificar con log HEAD..origin |
| Olvidar en submodulos | Referencias inconsistentes | Fetch en cada nivel |
---
## INCIDENTE DE ORIGEN
### INC-2026-01-16-001
**Descripcion:** Un agente reporto "working tree clean" cuando habia un commit
remoto (c027da53) que no habia sido detectado.
**Causa Raiz:** No se ejecuto `git fetch` antes de verificar estado con `git status`.
**Impacto:** Usuario confundido sobre el estado real del repositorio.
**Resolucion:**
- Creado este trigger obligatorio
- Actualizado SIMCO-GIT.md v1.2.0 con regla critica
- Actualizado SIMCO-SUBMODULOS.md v1.1.0 con secuencia obligatoria
- Documentado en TRAZA-GIT-OPERATIONS.md
---
## VERIFICACION RAPIDA
```bash
# Comando unico para verificar sincronizacion completa
git fetch origin && git log HEAD..origin/main --oneline && git status
# Salida esperada si todo sincronizado:
# (sin output del log)
# On branch main
# Your branch is up to date with 'origin/main'.
# nothing to commit, working tree clean
```
---
## INTEGRACION CON CAPVED
Este trigger se ejecuta en:
- **Pre-Tarea:** SIEMPRE antes de iniciar cualquier tarea
- **Pre-Commit:** Antes de hacer commit (verificar no hay conflictos)
- **Pre-Push:** Antes de push (verificar no hay rechazos pendientes)
- **Post-Pausa:** Al retomar trabajo despues de interrupcion
```yaml
pre_tarea:
primer_paso: "git fetch origin"
verificar: "git log HEAD..origin/main"
sincronizar_si_necesario: "git pull --no-recurse-submodules"
luego: "Continuar con la tarea"
```
---
## REFERENCIAS
- `orchestration/directivas/simco/SIMCO-GIT.md` - Directiva principal git (v1.2.0)
- `orchestration/directivas/simco/SIMCO-SUBMODULOS.md` - Protocolo submodulos (v1.1.0)
- `orchestration/SUBMODULES-POLICY.yml` - Politicas de sincronizacion (v1.1.0)
- `orchestration/trazas/TRAZA-GIT-OPERATIONS.md` - Registro de operaciones
- `orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md` - Trigger complementario
---
**Sistema:** SIMCO v4.0.0
**Mantenido por:** Workspace Admin

160
orchestration/directivas/triggers/TRIGGER-INICIO-TAREA.md Normal file
View File

@ -0,0 +1,160 @@
# ═══════════════════════════════════════════════════════════════════════════════
# TRIGGER-INICIO-TAREA
# ═══════════════════════════════════════════════════════════════════════════════
#
# Version: 1.0.0
# Creado: 2026-01-16
# Origen: Auditoría post-tarea TASK-2026-01-16-004
# Proposito: Garantizar creación de carpeta de tarea ANTES de ejecutar código
#
# ═══════════════════════════════════════════════════════════════════════════════
## CONDICION DE ACTIVACION
Este trigger se activa **AUTOMATICAMENTE** cuando:
1. Se recibe una solicitud que implica **modificar código**
2. Se recibe una solicitud que implica **crear archivos nuevos**
3. Se usa `@FULL` o `@CREATE-SAFE` o `@MODIFY-SAFE`
4. El primer item de TodoWrite incluye una tarea de implementación
**EXCEPCION:** No aplica para:
- Modo `@QUICK` en fixes menores (typos, config simple)
- Modo `@ANALYSIS` (solo investigación)
- Tareas puramente de lectura/exploración
---
## ACCION OBLIGATORIA
### Paso 1: Generar ID de Tarea
```
TASK-{YYYY-MM-DD}-{NNN}
```
Donde:
- `YYYY-MM-DD`: Fecha actual
- `NNN`: Siguiente secuencial del día (consultar `_INDEX.yml`)
### Paso 2: Crear Estructura de Carpeta
```bash
# Ruta base
orchestration/tareas/TASK-{ID}/
# Archivos mínimos obligatorios
├── METADATA.yml # Copiar de _templates/TASK-TEMPLATE/
├── 01-CONTEXTO.md # Llenar con clasificación inicial
└── (otros según avance)
```
### Paso 3: Registrar en Inventario
Agregar entrada en `tareas_activas` de `_INDEX.yml`:
```yaml
tareas_activas:
- task_id: "TASK-2026-01-XX-NNN"
titulo: "Título descriptivo"
agente: "PERFIL-AGENTE"
estado: "en_progreso"
fase: "C" # Inicia en Contexto
proyecto: "nombre-proyecto"
```
### Paso 4: Incluir en TodoWrite
El **PRIMER item** de TodoWrite debe ser:
```
- Crear carpeta de tarea TASK-{ID} en orchestration/tareas/
```
O si ya existe:
```
- Documentar contexto en TASK-{ID}/01-CONTEXTO.md
```
---
## CHECKPOINT DE VALIDACION
**ANTES de ejecutar cualquier código (fase E):**
```
[ ] ¿Existe carpeta orchestration/tareas/TASK-{ID}/?
[ ] ¿Existe METADATA.yml con información básica?
[ ] ¿Se registró en _INDEX.yml como tarea activa?
[ ] ¿TodoWrite incluye la tarea de documentación?
```
**SI algún checkbox falla:** BLOQUEAR ejecución hasta completar.
---
## INTEGRACION CON TODOWRITE
Cuando se use TodoWrite para planificar una tarea de código, incluir SIEMPRE:
```typescript
// Ejemplo de TodoWrite correcto
[
{ content: "Crear carpeta TASK-2026-01-16-004", status: "pending" },
{ content: "Documentar contexto y clasificación", status: "pending" },
{ content: "Analizar dependencias", status: "pending" },
// ... tareas técnicas ...
{ content: "Actualizar _INDEX.yml al completar", status: "pending" }
]
```
---
## REFERENCIAS
- `@TAREAS` - orchestration/tareas/
- `@NUEVA-TAREA` - orchestration/tareas/_templates/TASK-TEMPLATE/
- `@TRIGGER-DOC` - TRIGGER-DOCUMENTACION-OBLIGATORIA.md
- `@MAPA-DOC` - orchestration/MAPA-DOCUMENTACION.yml
---
## CASO DE ESTUDIO: TASK-2026-01-16-004
Esta directiva nace del análisis post-mortem de la tarea:
**"Integración de Servicios de API en Trading Platform Frontend"**
### Problema Detectado
- La tarea se ejecutó correctamente (build pasa, código funcional)
- PERO no se creó carpeta de tarea antes de ejecutar
- No se documentaron fases C, A, P, V formalmente
- No se actualizó _INDEX.yml hasta auditoría posterior
### Causa Raíz
1. No existía trigger bloqueante para creación de carpeta
2. TodoWrite no recordaba incluir checkpoint de gobernanza
3. Las reglas estaban en CLAUDE.md pero sin enforcement automático
### Solución Implementada
1. Crear este trigger (TRIGGER-INICIO-TAREA)
2. Documentación retroactiva de la tarea
3. Actualización de _INDEX.yml
4. Propuesta de mejora a flujo de TodoWrite
---
## METRICAS DE CUMPLIMIENTO
| Métrica | Objetivo | Medición |
|---------|----------|----------|
| Tareas con carpeta antes de E | 100% | `tareas_con_carpeta / total_tareas` |
| Fases documentadas por tarea | >= 3 | `promedio(fases_doc)` |
| _INDEX.yml actualizado | 100% | `tareas_en_index / total_tareas` |
---
# ═══════════════════════════════════════════════════════════════════════════════
# FIN DEL TRIGGER
# ═══════════════════════════════════════════════════════════════════════════════

281
orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md Normal file
View File

@ -0,0 +1,281 @@
# TRIGGER: INVENTARIOS SINCRONIZADOS
**Versión:** 1.0.0
**Fecha:** 2026-01-16
**Sistema:** SIMCO v4.0.0
**Alias:** @TRIGGER_INVENTARIOS
---
## RESUMEN EJECUTIVO
Este trigger OBLIGA a mantener los inventarios sincronizados con el código real. Se activa al completar cualquier tarea que modifique código o estructura.
**PRINCIPIO:** "Los inventarios son la fuente de verdad. Si no está en el inventario, no existe oficialmente."
---
## CONDICIONES DE ACTIVACIÓN
```yaml
activar_cuando:
- Se completa cualquier tarea con cambios de código
- Se crea/modifica/elimina: tabla, entity, service, módulo, componente
- Se ejecuta auditoría de proyecto
- Han pasado más de 7 días desde última sincronización
```
---
## INVENTARIOS REQUERIDOS POR PROYECTO
```yaml
inventarios_obligatorios:
DATABASE_INVENTORY.yml:
contenido:
- Lista completa de schemas
- Lista completa de tablas por schema
- Conteo de funciones, triggers, policies
- Estado de cada objeto (active/deprecated/planned)
actualizar_cuando:
- Crear/modificar/eliminar tabla
- Crear/modificar/eliminar schema
- Agregar/modificar funciones o triggers
BACKEND_INVENTORY.yml:
contenido:
- Lista completa de módulos
- Lista completa de entities por módulo
- Lista completa de services por módulo
- Conteo de endpoints por módulo
- Estado de cada objeto
actualizar_cuando:
- Crear/modificar/eliminar entity
- Crear/modificar/eliminar service
- Crear/modificar/eliminar módulo
- Agregar/modificar endpoints
FRONTEND_INVENTORY.yml:
contenido:
- Lista completa de componentes
- Lista completa de páginas
- Lista completa de hooks/stores
- Estado de cada objeto
actualizar_cuando:
- Crear/modificar/eliminar componente
- Crear/modificar/eliminar página
- Crear/modificar/eliminar hook/store
MASTER_INVENTORY.yml:
contenido:
- Resumen de todos los inventarios
- Totales consolidados
- Última fecha de sincronización
- Score de coherencia
actualizar_cuando:
- Se actualiza cualquier otro inventario
```
---
## VERIFICACIONES DE SINCRONIZACIÓN
### 1. Verificar Cobertura de Inventarios
```yaml
cobertura_minima:
DATABASE_INVENTORY:
schemas: "100% de schemas en DDL"
tablas: "100% de tablas en DDL"
funciones: "100% de funciones en DDL"
BACKEND_INVENTORY:
modulos: "100% de carpetas en modules/"
entities: "100% de archivos .entity.ts"
services: "100% de archivos .service.ts"
FRONTEND_INVENTORY:
componentes: "100% de archivos .tsx en components/"
paginas: "100% de archivos en pages/"
stores: "100% de stores/hooks"
```
### 2. Verificar Consistencia de Conteos
```yaml
validacion_conteos:
comparar:
- "Conteo en inventario vs archivos reales"
- "Conteo reportado en _INDEX.yml vs inventario"
- "Conteo entre inventarios relacionados"
tolerancia: "0% - Debe ser exacto"
si_discrepancia:
accion: "BLOQUEAR hasta sincronizar"
```
### 3. Verificar Actualización Reciente
```yaml
frescura:
maxima_antiguedad: "7 días"
verificar:
- "Fecha de última actualización en inventario"
- "Comparar con fecha de último commit en código"
si_desactualizado:
accion: "ADVERTIR y solicitar sincronización"
```
---
## PROCESO DE SINCRONIZACIÓN
### Sincronización Manual
```bash
# El agente debe ejecutar para cada inventario:
# 1. Contar objetos reales
find apps/database/ddl -name "*.sql" -exec grep -l "CREATE TABLE" {} \; | wc -l
find apps/backend/src/modules -name "*.entity.ts" | wc -l
find apps/backend/src/modules -name "*.service.ts" | wc -l
# 2. Comparar con inventario
# 3. Actualizar inventario si hay discrepancia
# 4. Actualizar timestamp de sincronización
```
### Campos Obligatorios en Inventarios
```yaml
metadata_obligatoria:
version: "Semver del inventario"
updated: "Fecha ISO de última actualización"
updated_by: "Agente que actualizó"
sync_status: "SYNCED | OUT_OF_SYNC | PARTIAL"
coverage:
total_expected: "N objetos esperados"
total_documented: "N objetos documentados"
percentage: "100%"
```
---
## CHECKLIST DE SINCRONIZACIÓN
### Al Completar Tarea
```markdown
## Verificación de Inventarios
### DATABASE_INVENTORY.yml
[ ] Conteo de schemas correcto
[ ] Conteo de tablas correcto
[ ] Nuevos objetos agregados
[ ] Objetos eliminados removidos
[ ] Timestamp actualizado
### BACKEND_INVENTORY.yml
[ ] Conteo de módulos correcto
[ ] Conteo de entities correcto
[ ] Conteo de services correcto
[ ] Conteo de endpoints correcto
[ ] Nuevos objetos agregados
[ ] Timestamp actualizado
### FRONTEND_INVENTORY.yml
[ ] Conteo de componentes correcto
[ ] Conteo de páginas correcto
[ ] Nuevos objetos agregados
[ ] Timestamp actualizado
### MASTER_INVENTORY.yml
[ ] Totales consolidados correctos
[ ] Score de coherencia actualizado
[ ] Timestamp actualizado
```
---
## INTEGRACIÓN CON TRIGGER-COHERENCIA-CAPAS
```yaml
secuencia:
1: "TRIGGER-COHERENCIA-CAPAS verifica estructura"
2: "TRIGGER-INVENTARIOS-SINCRONIZADOS verifica documentación"
3: "TRIGGER-DOCUMENTACION-OBLIGATORIA verifica gobernanza"
dependencia:
- "Coherencia debe pasar ANTES de sincronizar inventarios"
- "Inventarios deben estar sincronizados ANTES de documentar"
```
---
## MENSAJES DE ERROR
```yaml
errores:
E-INV-001:
mensaje: "Inventario desactualizado (más de 7 días)"
accion: "Ejecutar sincronización de inventario"
bloqueante: false (advertencia)
E-INV-002:
mensaje: "Discrepancia de conteo en inventario"
accion: "Sincronizar inventario con código real"
bloqueante: true
E-INV-003:
mensaje: "Objeto en código no documentado en inventario"
accion: "Agregar objeto al inventario"
bloqueante: true
E-INV-004:
mensaje: "Objeto en inventario no existe en código"
accion: "Remover objeto del inventario o restaurar código"
bloqueante: true
E-INV-005:
mensaje: "Inventario faltante"
accion: "Crear inventario siguiendo template"
bloqueante: true
```
---
## AUTOMATIZACIÓN FUTURA
```yaml
scripts_recomendados:
sync-database-inventory:
descripcion: "Sincronizar DATABASE_INVENTORY.yml automáticamente"
implementar_en: "scripts/sync-inventories.sh"
sync-backend-inventory:
descripcion: "Sincronizar BACKEND_INVENTORY.yml automáticamente"
implementar_en: "scripts/sync-inventories.sh"
validate-inventories:
descripcion: "Validar que todos los inventarios estén sincronizados"
implementar_en: "scripts/validate-inventories.sh"
estado: "DOCUMENTADO - Por implementar"
```
---
## REFERENCIAS
| Alias | Descripción |
|-------|-------------|
| @TRIGGER_INVENTARIOS | Este trigger |
| @TRIGGER_COHERENCIA | Coherencia entre capas |
| @DEF_CHK_POST | Checklist post-tarea |
---
**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Trigger de Sincronización

22
orchestration/inventarios/BACKEND_INVENTORY.yml Normal file
View File

@ -0,0 +1,22 @@
# BACKEND_INVENTORY.yml - clinica-dental
# Generado: 2026-01-18T13:01:47-06:00
project: "clinica-dental"
layer: "backend"
modules: []
entities: []
services: []
controllers: []
total:
modules: 0
entities: 0
services: 0
controllers: 0
tests: 0
last_updated: "2026-01-18T13:01:47-06:00"

291
orchestration/inventarios/DATABASE_INVENTORY.yml
View File

@ -1,284 +1,21 @@
--- # DATABASE_INVENTORY.yml - clinica-dental
# DATABASE INVENTORY - Clinica Dental # Generado: 2026-01-18T13:01:47-06:00
# Version: 1.0.0
# Ultima actualizacion: 2026-01-07
proyecto: "clinica-dental" project: "clinica-dental"
schema_principal: "dental" layer: "database"
version_ddl: "1.0"
estado: "completado"
herencia: schemas: []
vertical_padre: "erp-clinicas"
suite_core: "erp-core"
schemas_heredados:
- name: "auth"
desde: "erp-core"
- name: "tenants"
desde: "erp-core"
- name: "users"
desde: "erp-core"
- name: "clinica"
desde: "erp-clinicas"
tablas: ["patients", "doctors", "appointments", "consultations"]
enums: tables: []
- name: "estado_pieza"
values:
- "sano"
- "caries"
- "obturacion"
- "endodoncia"
- "corona"
- "puente"
- "implante"
- "ausente"
- "extraccion_indicada"
- "diente_temporal"
- "fractura"
- "movilidad"
- name: "cara_dental" functions: []
values:
- "mesial"
- "distal"
- "oclusal"
- "incisal"
- "vestibular"
- "bucal"
- "lingual"
- "palatino"
- name: "estado_tratamiento" triggers: []
values:
- "pendiente"
- "en_proceso"
- "completado"
- "cancelado"
- name: "tipo_ortodoncia" total:
values: schemas: 0
- "brackets_metalicos" tables: 0
- "brackets_esteticos" functions: 0
- "brackets_linguales" triggers: 0
- "alineadores"
- "removible"
- "retenedor"
catalogos: last_updated: "2026-01-18T13:01:47-06:00"
- name: "piezas_dentales"
descripcion: "Catalogo de piezas dentales (nomenclatura FDI)"
registros: 52
columnas:
- "id: UUID PK"
- "numero: VARCHAR(10) UNIQUE"
- "nombre: VARCHAR(50)"
- "cuadrante: INTEGER (1-8)"
- "es_temporal: BOOLEAN"
- "descripcion: TEXT"
- name: "tratamientos_catalogo"
descripcion: "Catalogo de tratamientos por tenant"
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "codigo: VARCHAR(20)"
- "nombre: VARCHAR(100)"
- "categoria: VARCHAR(50)"
- "duracion_minutos: INTEGER"
- "precio_base: NUMERIC(10,2)"
- "requiere_rx: BOOLEAN"
- "requiere_anestesia: BOOLEAN"
tablas:
- name: "odontogramas"
descripcion: "Odontogramas de pacientes"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "patient_id: UUID FK (clinica.patients)"
- "fecha_creacion: DATE"
- "fecha_actualizacion: DATE"
- "notas: TEXT"
indices:
- "idx_odontogramas_tenant"
- "idx_odontogramas_patient"
- name: "odontograma_piezas"
descripcion: "Estado de cada pieza en el odontograma"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "odontograma_id: UUID FK"
- "pieza_id: UUID FK (piezas_dentales)"
- "estado: dental.estado_pieza"
- "caras_afectadas: JSONB"
- "observaciones: TEXT"
indices:
- "idx_odontograma_piezas_odontograma"
- "idx_odontograma_piezas_pieza"
- name: "tratamientos_paciente"
descripcion: "Tratamientos realizados a pacientes"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "patient_id: UUID FK"
- "odontograma_id: UUID FK"
- "tratamiento_id: UUID FK (tratamientos_catalogo)"
- "odontologo_id: UUID FK"
- "consultation_id: UUID FK"
- "pieza_id: UUID FK"
- "caras_tratadas: dental.cara_dental[]"
- "fecha_inicio: DATE"
- "fecha_fin: DATE"
- "estado: dental.estado_tratamiento"
- "precio: NUMERIC(10,2)"
- "descuento: NUMERIC(5,2)"
- "precio_final: NUMERIC(10,2)"
indices:
- "idx_tratamientos_paciente_tenant"
- "idx_tratamientos_paciente_patient"
- "idx_tratamientos_paciente_estado"
- name: "ortodoncia"
descripcion: "Casos de ortodoncia"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "patient_id: UUID FK"
- "odontologo_id: UUID FK"
- "tipo: dental.tipo_ortodoncia"
- "marca: VARCHAR(100)"
- "fecha_inicio: DATE"
- "fecha_estimada_fin: DATE"
- "fecha_real_fin: DATE"
- "estado: dental.estado_tratamiento"
- "meses_estimados: INTEGER"
- "costo_total: NUMERIC(10,2)"
- "enganche: NUMERIC(10,2)"
- "mensualidad: NUMERIC(10,2)"
indices:
- "idx_ortodoncia_tenant"
- "idx_ortodoncia_patient"
- "idx_ortodoncia_estado"
- name: "ortodoncia_citas"
descripcion: "Citas de seguimiento de ortodoncia"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "ortodoncia_id: UUID FK"
- "appointment_id: UUID FK"
- "fecha: DATE"
- "numero_cita: INTEGER"
- "procedimiento: TEXT"
- "arco_superior: VARCHAR(50)"
- "arco_inferior: VARCHAR(50)"
- "ligas: VARCHAR(50)"
- "proxima_cita: DATE"
indices:
- "idx_ortodoncia_citas_ortodoncia"
- name: "protesis"
descripcion: "Trabajos protesicos"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "patient_id: UUID FK"
- "odontologo_id: UUID FK"
- "tipo: VARCHAR(50)"
- "piezas_involucradas: TEXT[]"
- "laboratorio_id: UUID FK"
- "fecha_envio_lab: DATE"
- "fecha_recepcion_lab: DATE"
- "material: VARCHAR(100)"
- "color: VARCHAR(50)"
- "estado: dental.estado_tratamiento"
- "fecha_colocacion: DATE"
- "tiene_garantia: BOOLEAN"
- "meses_garantia: INTEGER"
- "costo_laboratorio: NUMERIC(10,2)"
- "precio_paciente: NUMERIC(10,2)"
indices:
- "idx_protesis_tenant"
- "idx_protesis_patient"
- name: "radiografias"
descripcion: "Radiografias dentales"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "patient_id: UUID FK"
- "consultation_id: UUID FK"
- "tipo: VARCHAR(50)"
- "pieza_id: UUID FK"
- "fecha: DATE"
- "url_imagen: VARCHAR(255)"
- "interpretacion: TEXT"
indices:
- "idx_radiografias_tenant"
- "idx_radiografias_patient"
- name: "presupuestos"
descripcion: "Presupuestos de tratamiento"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "patient_id: UUID FK"
- "odontologo_id: UUID FK"
- "numero: VARCHAR(20)"
- "fecha: DATE"
- "fecha_vencimiento: DATE"
- "estado: VARCHAR(20)"
- "subtotal: NUMERIC(12,2)"
- "descuento_porcentaje: NUMERIC(5,2)"
- "descuento_monto: NUMERIC(12,2)"
- "total: NUMERIC(12,2)"
- "requiere_financiamiento: BOOLEAN"
- "enganche: NUMERIC(12,2)"
- "numero_pagos: INTEGER"
- "monto_pago: NUMERIC(12,2)"
indices:
- "idx_presupuestos_tenant"
- "idx_presupuestos_patient"
- "idx_presupuestos_estado"
- name: "presupuesto_lineas"
descripcion: "Lineas de presupuesto"
rls: true
columnas:
- "id: UUID PK"
- "tenant_id: UUID FK"
- "presupuesto_id: UUID FK"
- "tratamiento_id: UUID FK"
- "pieza_id: UUID FK"
- "descripcion: TEXT"
- "cantidad: INTEGER"
- "precio_unitario: NUMERIC(10,2)"
- "descuento: NUMERIC(5,2)"
- "subtotal: NUMERIC(10,2)"
- "sequence: INTEGER"
indices:
- "idx_presupuesto_lineas_presupuesto"
resumen:
total_enums: 4
total_catalogos: 2
total_tablas: 10
total_con_rls: 10
archivos_ddl:
- "database/schemas/01-dental-schema-ddl.sql"
archivos_seeds:
- "database/seeds/fase8/01-dental-catalogos.sql"
ultima_actualizacion: "2026-01-07"
actualizado_por: "Orquestador Workspace"

24
orchestration/inventarios/FRONTEND_INVENTORY.yml Normal file
View File

@ -0,0 +1,24 @@
# FRONTEND_INVENTORY.yml - clinica-dental
# Generado: 2026-01-18T13:01:47-06:00
project: "clinica-dental"
layer: "frontend"
features: []
components: []
pages: []
stores: []
hooks: []
total:
features: 0
components: 0
pages: 0
stores: 0
hooks: 0
last_updated: "2026-01-18T13:01:47-06:00"

176
orchestration/inventarios/MASTER_INVENTORY.yml
View File

@ -1,159 +1,25 @@
--- # MASTER_INVENTORY.yml - clinica-dental
# MASTER INVENTORY - Clinica Dental # Generado: 2026-01-18T13:01:47-06:00
# Version: 1.1.0 # Version: 1.0.0
# Ultima actualizacion: 2026-01-13
proyecto: "clinica-dental" project:
descripcion: "ERP especializado para clinicas dentales" name: "clinica-dental"
version: "1.0.0" type: "erp-vertical"
estado: "desarrollo" parent: "erp-core"
tipo: "sub-vertical" version: "0.1.0"
base: "erp-clinicas"
progreso: summary:
fase_actual: "Database" total_modules: 0
porcentaje: 25 backend_entities: 0
database_completado: true frontend_components: 0
backend_completado: false database_tables: 0
frontend_completado: false test_files: 0
coverage_percentage: 0
# Cadena de herencia completa inventories:
herencia: backend: "BACKEND_INVENTORY.yml"
cadena: "template-saas -> erp-core -> erp-clinicas -> clinica-dental" frontend: "FRONTEND_INVENTORY.yml"
vertical_padre: "erp-clinicas" database: "DATABASE_INVENTORY.yml"
suite_core: "erp-core"
provider: "template-saas"
# Módulos heredados por fase last_updated: "2026-01-18T13:01:47-06:00"
modulos_heredados: updated_by: "propagate-governance.sh"
fase_01_02_core:
- MGN-001 (auth)
- MGN-002 (users)
- MGN-003 (roles)
- MGN-004 (tenants)
- MGN-005 (catalogs)
- MGN-007 (audit)
- MGN-008 (notifications)
- MGN-009 (reports)
fase_04_saas:
- MGN-016 (billing)
- MGN-017 (plans)
- MGN-018 (webhooks)
- MGN-019 (feature-flags)
fase_05_ia:
- MGN-020 (ai-integration)
- MGN-021 (whatsapp-business)
- MGN-022 (mcp-server)
erp_clinicas:
- CL-001 (fundamentos)
- CL-002 (pacientes)
- CL-003 (citas)
- CL-004 (consultas)
- CL-005 (recetas)
- CL-006 (laboratorio)
- CL-007 (farmacia)
- CL-008 (facturacion)
- CL-009 (reportes)
- CL-010 (telemedicina)
- CL-011 (expediente)
- CL-012 (imagenologia)
total_modulos_heredados: 29 # 17 erp-core + 12 erp-clinicas
# Propagación recibida
ultima_propagacion:
id: "PROP-CORE-002"
fecha: "2026-01-13"
tipo: "bulk_propagation"
modulos_recibidos:
- MGN-016 a MGN-022 (Fases 04-05)
modulos_especificos:
- id: "DENTAL-001"
nombre: "odontograma"
descripcion: "Registro grafico del estado dental"
estado: "ddl_completado"
- id: "DENTAL-002"
nombre: "tratamientos-dentales"
descripcion: "Procedimientos odontologicos"
estado: "ddl_completado"
- id: "DENTAL-003"
nombre: "ortodoncia"
descripcion: "Control de tratamientos ortodonticos"
estado: "ddl_completado"
- id: "DENTAL-004"
nombre: "protesis"
descripcion: "Registro de trabajos protesicos"
estado: "ddl_completado"
- id: "DENTAL-005"
nombre: "radiografias"
descripcion: "Registro de radiografias dentales"
estado: "documentado"
- id: "DENTAL-006"
nombre: "presupuestos"
descripcion: "Presupuestos de tratamiento"
estado: "documentado"
database:
schema: "dental"
archivo_ddl: "database/schemas/01-dental-schema-ddl.sql"
archivo_seeds: "database/seeds/fase8/01-dental-catalogos.sql"
tablas_especificas:
- "dental_pieces"
- "dental_charts"
- "dental_treatments"
- "orthodontic_cases"
- "prosthetics"
schemas_heredados:
- billing (Fase 04)
- webhooks (Fase 04)
- feature_flags (Fase 04)
- ai_agents (Fase 05)
- messaging (Fase 05)
catalogos:
- "especialidades_odontologicas"
- "estados_piezas_dentales"
- "caras_dentales"
- "tipos_tratamiento_dental"
# Adaptaciones IA para dental
ia_adaptations:
mcp_tools:
- crear_cita_dental
- consultar_odontograma
- presupuesto_tratamiento
- historial_tratamientos
whatsapp_templates:
- recordatorio_cita_dental
- confirmacion_cita
- seguimiento_tratamiento
- promocion_limpieza
normativa:
- NOM-013-SSA2-2015
- NOM-004-SSA3-2012
- NOM-024-SSA3-2012
- LFPDPPP
- COFEPRIS
proximas_tareas:
- "Implementar backend modulo odontograma"
- "Crear frontend para odontograma digital"
- "Configurar feature flags para dental"
- "Crear templates WhatsApp para citas"
- "Integrar MCP tools odontologicos"
documentos_referencia:
- "orchestration/00-guidelines/HERENCIA-ERP-CORE.md"
- "orchestration/00-guidelines/HERENCIA-ERP-CLINICAS.md"
- "orchestration/referencias/DEPENDENCIAS-ERP-CORE.yml"
ultima_actualizacion: "2026-01-13"
actualizado_por: "CLAUDE-CAPVED"
propagacion_ref: "PROP-CORE-002"