workspace-v1/orchestration/directivas/simco/SIMCO-PROPAGACION.md

SIMCO: PROPAGACIÓN DE DOCUMENTACIÓN

Versión: 1.0.0 Fecha: 2025-12-08 Aplica a: Todos los agentes al completar tareas Prioridad: OBLIGATORIA - Ejecutar DESPUÉS de cada tarea completada Prerequisito: SIMCO-NIVELES.md (identificación de nivel)

---

RESUMEN EJECUTIVO

Toda tarea completada DEBE propagar su documentación hacia niveles superiores. Propagación incompleta = referencias rotas, inventarios desactualizados, trazabilidad perdida. La tarea NO está completa hasta que la propagación esté verificada.

---

PRINCIPIO DE PROPAGACIÓN

╔══════════════════════════════════════════════════════════════════════╗
║  FLUJO DE PROPAGACIÓN: Siempre de ABAJO hacia ARRIBA                 ║
║                                                                       ║
║  Vertical → Suite → Workspace                                         ║
║  Suite Core → Suite → Workspace                                       ║
║  Standalone → Workspace                                               ║
║  Core → Workspace                                                     ║
║  Catálogo → Core → Workspace                                          ║
╚══════════════════════════════════════════════════════════════════════╝

---

MATRIZ DE PROPAGACIÓN

Por Nivel de Origen

Nivel Origen	Propaga a Nivel 1	Propaga a Nivel 2	Propaga a Nivel 3
2B.2 VERTICAL	2B SUITE	0 WORKSPACE	-
2B.1 SUITE-CORE	2B SUITE	0 WORKSPACE	-
2B SUITE	0 WORKSPACE	-	-
2A STANDALONE	0 WORKSPACE	-	-
1 CORE	0 WORKSPACE	-	-
3 CATÁLOGO	1 CORE	0 WORKSPACE	-

Qué Propagar

PROPAGACION_CONTENIDO:
  inventario:
    tipo: "REFERENCIA"
    contenido: "Puntero al artefacto, NO duplicar contenido"
    ejemplo: "ref: verticals/construccion/backend/entities/Obra.entity.ts"

  traza:
    tipo: "RESUMEN"
    contenido: "Entrada resumida de la tarea completada"
    ejemplo: "[2025-12-08] Vertical:Construccion - Creada entity Obra"

  status:
    tipo: "ACTUALIZACIÓN"
    contenido: "Cambiar estado del componente/módulo"
    ejemplo: "construccion.backend.entities: UPDATED"

  indice:
    tipo: "ENTRADA"
    contenido: "Agregar a índices si es artefacto nuevo"
    ejemplo: "Nueva entrada en VERTICALES-INDEX.yml"

---

PROTOCOLO DE PROPAGACIÓN

Fase 1: Documentar en Nivel Actual

PASO_1_DOCUMENTAR_LOCAL:
  ubicacion: "{ORCHESTRATION_PATH del nivel actual}"

  acciones:
    - actualizar_inventario:
        archivo: "{INVENTORY}.yml"
        contenido: "Artefacto completo con todos los campos"

    - registrar_traza:
        archivo: "trazas/TRAZA-TAREAS-{CAPA}.md"
        contenido: "Entrada completa con fecha, descripción, archivos"

    - actualizar_proxima_accion:
        archivo: "PROXIMA-ACCION.md"
        contenido: "Si hay siguiente paso, documentarlo"

  validacion:
    - [ ] Inventario actualizado
    - [ ] Traza registrada
    - [ ] Sin errores de formato

Fase 2: Propagar a Niveles Superiores

PASO_2_PROPAGAR:
  para_cada_nivel_en: "PROPAGATE_TO"

  acciones:
    - agregar_referencia:
        archivo: "{nivel_superior}/inventarios/{INVENTORY}.yml"
        tipo: "referencia"
        contenido: |
          - ref: "{ruta_relativa_al_artefacto}"
            nivel: "{nivel_origen}"
            fecha: "{fecha}"
            estado: "NUEVO|MODIFICADO"          

    - actualizar_status:
        archivo: "{nivel_superior}/inventarios/STATUS.yml"
        contenido: "Marcar componente como actualizado"

    - registrar_en_traza:
        archivo: "{nivel_superior}/trazas/TRAZA-{tipo}.md"
        contenido: |
          ## [{fecha}] Propagación desde {nivel_origen}
          - **Origen:** {ruta_completa}
          - **Artefacto:** {nombre}
          - **Acción:** {CREAR|MODIFICAR|ELIMINAR}          

  validacion:
    - [ ] Todas las referencias agregadas
    - [ ] Status actualizados
    - [ ] Trazas registradas

Fase 3: Verificar Coherencia

PASO_3_VERIFICAR:
  acciones:
    - verificar_referencias:
        comando: "Validar que todas las refs apuntan a archivos existentes"

    - verificar_indices:
        comando: "Validar que índices incluyen nuevos artefactos"

    - verificar_status:
        comando: "Validar que status reflejan cambios"

  si_hay_error:
    - Corregir inmediatamente
    - NO marcar tarea como completa hasta resolver

---

TEMPLATES DE PROPAGACIÓN

Template: Referencia en Inventario Superior

# En {nivel_superior}/inventarios/REFERENCIAS.yml

referencias_desde_{nivel_origen}:
  - id: "{uuid o identificador}"
    ruta: "{ruta_relativa_completa}"
    tipo: "{entity|service|component|table|etc}"
    nivel_origen: "{NIVEL_X}"
    fecha_creacion: "{YYYY-MM-DD}"
    fecha_modificacion: "{YYYY-MM-DD}"
    estado: "{ACTIVO|DEPRECADO}"
    descripcion: "{breve descripción}"

Template: Entrada en Traza Superior

## [{YYYY-MM-DD HH:MM}] Propagación: {Nivel Origen}

### Origen
- **Nivel:** {NIVEL_X}
- **Ruta:** `{ruta_completa}`
- **Proyecto/Vertical:** {nombre}

### Cambio
- **Tipo:** {CREAR|MODIFICAR|ELIMINAR}
- **Artefacto:** {nombre del artefacto}
- **Capa:** {DATABASE|BACKEND|FRONTEND}

### Impacto
- **Dependencias afectadas:** {lista o "ninguna"}
- **Requiere acción en otros niveles:** {sí/no}

### Referencias
- Inventario local: `{ruta_inventario_origen}`
- Traza local: `{ruta_traza_origen}`

Template: Actualización de Status

# En {nivel_superior}/inventarios/STATUS.yml

componentes:
  {nombre_componente}:
    nivel: "{NIVEL_X}"
    ultima_modificacion: "{YYYY-MM-DD}"
    modificado_por: "{agente}"
    estado: "{ESTABLE|EN_DESARROLLO|DEPRECADO}"
    artefactos_recientes:
      - "{artefacto_1}"
      - "{artefacto_2}"

---

CASOS DE PROPAGACIÓN

Caso 1: Crear Entity en Vertical

ESCENARIO:
  nivel: "2B.2 VERTICAL (construccion)"
  accion: "Crear Obra.entity.ts"
  ruta: "projects/nexus-erp-suite/verticals/construccion/backend/src/modules/obra/entities/Obra.entity.ts"

PROPAGACION:
  paso_1_local:
    archivo: "verticals/construccion/orchestration/inventarios/BACKEND_INVENTORY.yml"
    contenido: |
      entities:
        - name: Obra
          file: src/modules/obra/entities/Obra.entity.ts
          table: obra.obras
          created: 2025-12-08
          status: NUEVO      

  paso_2_suite:
    archivo: "projects/nexus-erp-suite/orchestration/inventarios/REFERENCIAS.yml"
    contenido: |
      referencias_verticales:
        construccion:
          backend:
            entities:
              - ref: verticals/construccion/backend/src/modules/obra/entities/Obra.entity.ts
                nombre: Obra
                fecha: 2025-12-08      

  paso_3_workspace:
    archivo: "orchestration/WORKSPACE-STATUS.md"
    contenido: |
      ## Actividad Reciente
      - [2025-12-08] nexus-erp-suite/construccion: Nueva entity Obra      

Caso 2: Modificar Funcionalidad del Catálogo

ESCENARIO:
  nivel: "3 CATÁLOGO"
  accion: "Actualizar auth module"
  ruta: "core/catalog/functionalities/auth/"

PROPAGACION:
  paso_1_local:
    archivo: "core/catalog/functionalities/auth/orchestration/CHANGELOG.md"
    contenido: "Detalle de cambios"

  paso_2_core:
    archivo: "core/orchestration/inventarios/CATALOG_STATUS.yml"
    contenido: |
      functionalities:
        auth:
          version: "1.2.0"
          ultima_modificacion: 2025-12-08
          cambios: "Descripción breve"      

  paso_3_workspace:
    archivo: "orchestration/WORKSPACE-STATUS.md"
    contenido: |
      ## Catálogo Actualizado
      - [2025-12-08] core/catalog/auth: Actualizado a v1.2.0      

  paso_4_notificar_consumidores:
    # Proyectos que usan auth deben ser notificados
    consultar: "core/catalog/functionalities/auth/orchestration/CONSUMIDORES.yml"
    accion: "Agregar nota de actualización disponible"

Caso 3: Crear Tabla en Suite Core

ESCENARIO:
  nivel: "2B.1 SUITE-CORE"
  accion: "Crear tabla shared.audit_logs"
  ruta: "projects/nexus-erp-suite/core/database/ddl/schemas/shared/tables/01-audit_logs.sql"

PROPAGACION:
  paso_1_local:
    archivo: "projects/nexus-erp-suite/core/orchestration/inventarios/DATABASE_INVENTORY.yml"
    contenido: |
      tables:
        shared:
          - name: audit_logs
            file: ddl/schemas/shared/tables/01-audit_logs.sql
            created: 2025-12-08      

  paso_2_suite:
    archivo: "projects/nexus-erp-suite/orchestration/inventarios/SUITE_MASTER_INVENTORY.yml"
    contenido: |
      core:
        database:
          tablas_nuevas:
            - shared.audit_logs (2025-12-08)      

  paso_3_notificar_verticales:
    # Tabla compartida, verticales pueden usarla
    archivo: "projects/nexus-erp-suite/orchestration/trazas/TRAZA-SUITE.md"
    contenido: |
      ## [2025-12-08] Nueva tabla compartida disponible
      - **Tabla:** shared.audit_logs
      - **Uso:** Disponible para todos los verticales
      - **Documentación:** core/database/docs/audit_logs.md      

---

VALIDACIÓN POST-PROPAGACIÓN

Checklist de Verificación

## Validación de Propagación - {Tarea}

### Nivel Local ({NIVEL_X})
- [ ] Inventario actualizado con artefacto completo
- [ ] Traza registrada con todos los detalles
- [ ] PROXIMA-ACCION actualizado (si aplica)

### Nivel Superior 1 ({NIVEL_Y})
- [ ] Referencia agregada en inventario
- [ ] Status actualizado
- [ ] Traza con entrada de propagación

### Nivel Superior 2 ({NIVEL_Z}) - si aplica
- [ ] Referencia agregada
- [ ] Status actualizado
- [ ] Traza registrada

### Workspace (NIVEL_0)
- [ ] WORKSPACE-STATUS.md actualizado
- [ ] Índice de proyectos actualizado (si es nuevo)

### Coherencia
- [ ] Todas las referencias apuntan a archivos existentes
- [ ] No hay referencias duplicadas
- [ ] Fechas consistentes entre niveles
- [ ] Estados coherentes (NUEVO en todos o MODIFICADO en todos)

---

ERRORES COMUNES

Error	Causa	Solución
Referencia rota	Ruta mal calculada	Usar rutas relativas desde nivel superior
Duplicación de contenido	Copiar en vez de referenciar	Solo REFERENCIAS en niveles superiores
Propagación parcial	Olvidó un nivel	Verificar PROPAGATE_TO completo
Fechas inconsistentes	Copiar fecha antigua	Usar fecha actual de propagación
Status desincronizado	No actualizó todos los niveles	Ejecutar validación post-propagación

---

AUTOMATIZACIÓN (Futuro)

# Concepto para script de propagación automática

propagacion_automatica:
  trigger: "Al completar tarea"
  input:
    - nivel_actual
    - artefacto_creado
    - tipo_cambio

  proceso:
    1. Identificar PROPAGATE_TO
    2. Generar entradas de referencia
    3. Actualizar inventarios
    4. Registrar trazas
    5. Validar coherencia

  output:
    - Reporte de propagación
    - Lista de verificación

---

INTEGRACIÓN CON OTROS SIMCO

Con SIMCO-NIVELES

# SIMCO-NIVELES identifica el nivel
# SIMCO-PROPAGACION usa esa información

flujo:
  1. SIMCO-NIVELES → nivel_actual, PROPAGATE_TO
  2. Ejecutar tarea
  3. SIMCO-PROPAGACION → documentar y propagar

Con SIMCO-VALIDAR

# Incluir propagación en validación final

validacion_extendida:
  - Validación técnica (build, lint)
  - Validación de documentación local
  - Validación de propagación (NUEVO)

---

REFERENCIAS

• Niveles: SIMCO-NIVELES.md
• Validación: SIMCO-VALIDAR.md
• Templates: templates/PROPAGACION-*.md

---

Versión: 1.0.0 | Sistema: SIMCO | Tipo: Directiva de Propagación