workspace-v1/shared/knowledge-base/propagacion/USAGE.md

Guia de Uso: Sistema de Propagacion de Mejoras

Version: 1.0.0 Sistema: NEXUS v3.4 Directiva: @PROPAGACION Fecha: 2026-01-04

---

Quick Start (5 pasos)

# 1. Verificar estado actual de modulos
./devtools/scripts/propagation/check-module-versions.sh

# 2. Ver dashboard visual
./devtools/scripts/propagation/generate-propagation-report.sh

# 3. Iniciar propagacion de una mejora
./devtools/scripts/propagation/propagate-module-update.sh <modulo> <version> <origen>

# 4. Completar tareas generadas por proyecto

# 5. Actualizar TRAZABILIDAD-PROYECTOS.yml

---

Que es el Sistema de Propagacion?

El sistema de propagacion permite que cuando mejoras un modulo compartido en un proyecto, esa mejora se propague automaticamente a todos los proyectos que usan ese modulo.

Flujo basico

Tu mejora en Proyecto A
        |
        v
Se registra en Knowledge-Base
        |
        v
Se identifican proyectos B, C, D que usan el modulo
        |
        v
Se crean tareas de propagacion
        |
        v
Se propaga a cada proyecto
        |
        v
Se actualiza trazabilidad

---

Cuando Usar Este Sistema

Usar propagacion cuando:

• Corriges un bug en un modulo compartido
• Aplicas un fix de seguridad
• Agregas una feature generica que beneficia a otros
• Mejoras el performance de un modulo

NO usar propagacion cuando:

• El cambio es especifico de reglas de negocio de tu proyecto
• El cambio es puramente estetico o de estilo personal
• El modulo no existe en el knowledge-base

---

Comandos Disponibles

1. propagate-module-update.sh

Inicia el proceso de propagacion.

# Uso basico
./devtools/scripts/propagation/propagate-module-update.sh <modulo> <version> <origen>

# Ejemplo: Propagar mejora de auth-jwt-nestjs desde gamilit
./devtools/scripts/propagation/propagate-module-update.sh auth-jwt-nestjs 2.2.0 gamilit

# Simular sin hacer cambios
./devtools/scripts/propagation/propagate-module-update.sh auth-jwt-nestjs 2.2.0 gamilit --dry-run

# Actualizar registro automaticamente
./devtools/scripts/propagation/propagate-module-update.sh auth-jwt-nestjs 2.2.0 gamilit --update-registry

Output:

==========================================
  PROPAGATE MODULE UPDATE
  Sistema: NEXUS v3.4
==========================================

[OK] Modulo 'auth-jwt-nestjs' encontrado en catalogo
[OK] Proyecto origen 'gamilit' verificado

============================================
  PROPAGACION DE MEJORAS
============================================

  Modulo:         auth-jwt-nestjs
  Version nueva:  2.2.0
  Proyecto origen: gamilit

  Proyectos a propagar:
    - erp-core (tiene v2.1.0)
    - trading-platform (tiene v2.1.0)

2. check-module-versions.sh

Detecta modulos desactualizados.

# Verificar todos los modulos
./devtools/scripts/propagation/check-module-versions.sh

# Verificar un modulo especifico
./devtools/scripts/propagation/check-module-versions.sh --modulo auth-jwt-nestjs

# Verificar un proyecto especifico
./devtools/scripts/propagation/check-module-versions.sh --proyecto gamilit

# Modo verbose (mostrar todo, no solo desactualizados)
./devtools/scripts/propagation/check-module-versions.sh --verbose

Exit codes:

• 0 = Todos los proyectos al dia
• 1 = Hay desactualizaciones
• 2 = Error de configuracion

3. generate-propagation-report.sh

Genera dashboard visual.

# Dashboard en terminal
./devtools/scripts/propagation/generate-propagation-report.sh

# Sin colores (para logs)
./devtools/scripts/propagation/generate-propagation-report.sh --no-color

# Formato Markdown
./devtools/scripts/propagation/generate-propagation-report.sh --markdown

# Guardar a archivo
./devtools/scripts/propagation/generate-propagation-report.sh --output estado.md --markdown

---

Proceso Paso a Paso

Paso 1: Verificar si tu cambio es propagable

Preguntate:

1. El modulo existe en CATALOGO-MODULOS.yml?

   grep "tu-modulo" shared/knowledge-base/CATALOGO-MODULOS.yml
   

2. El cambio es generico (no especifico de tu proyecto)?

3. El cambio beneficia a otros proyectos?

Si la respuesta es SI a las tres, tu cambio es propagable.

Paso 2: Determinar tipo de cambio

Tipo	Descripcion	SLA
security-fix	Vulnerabilidad de seguridad	24 horas
bug-fix	Correccion de error	48 horas
feature	Nueva funcionalidad	Evaluar
refactor	Mejora interna	Opcional
performance	Optimizacion	Evaluar

Paso 3: Ejecutar script de propagacion

./devtools/scripts/propagation/propagate-module-update.sh \
    auth-jwt-nestjs \
    2.2.0 \
    gamilit

Paso 4: Revisar proyectos afectados

El script mostrara que proyectos necesitan recibir la propagacion.

Paso 5: Crear tareas de propagacion

Para cada proyecto destino:

1. Usar template templates/TAREA-PROPAGACION.md
2. Completar con datos del modulo y proyecto
3. Asignar a responsable del proyecto

Paso 6: Implementar en cada proyecto

En cada proyecto destino:

# 1. Crear branch
git checkout -b feat/upgrade-modulo-X.Y.Z

# 2. Aplicar cambios
# (segun guia de migracion si es breaking change)

# 3. Build y tests
npm run build
npm run test

# 4. Commit con mensaje estandar
git commit -m "chore(deps): propagate modulo vX.Y.Z from proyecto-origen

- Descripcion del cambio
- Propagation ID: PROP-2026-XXX

See: @PROPAGACION"

Paso 7: Actualizar registros

1. Actualizar REGISTRO-PROPAGACIONES.yml:

   • Marcar destino como "completado"
   • Agregar commit hash
   • Agregar fecha

2. Actualizar TRAZABILIDAD-PROYECTOS.yml:

   • Actualizar version del modulo en el proyecto
   • Actualizar ultima_sincronizacion

3. Actualizar HERENCIA-SIMCO.md del proyecto:

   • Actualizar tabla de modulos usados

---

Troubleshooting

"Modulo no encontrado en catalogo"

Problema: El modulo no esta registrado en knowledge-base.

Solucion:

1. Verificar nombre exacto del modulo
2. Si el modulo es nuevo, primero agregarlo a CATALOGO-MODULOS.yml
3. Ver EPIC-006 para proceso de agregar modulos

"Sin proyectos para propagar"

Problema: El modulo solo es usado por el proyecto origen.

Solucion: No es necesario propagar. La mejora ya esta aplicada.

"TRAZABILIDAD-PROYECTOS.yml no encontrado"

Problema: Archivos del knowledge-base no estan en su lugar.

Solucion:

ls -la /home/isem/workspace-v1/shared/knowledge-base/

Si no existe, ejecutar EPIC-006 primero.

"Breaking change detectado"

Problema: El cambio rompe compatibilidad.

Solucion:

1. Crear MIGRATION-X.Y-to-X.Z.md en el directorio del modulo
2. Marcar breaking_change: true en registro
3. Evaluar cada proyecto destino individualmente
4. Considerar crear EPIC dedicada si es muy complejo

---

FAQ

P: Que pasa si mi cambio es un breaking change?

R: Debes crear una guia de migracion (MIGRATION-X.Y-to-X.Z.md) y marcar breaking_change: true en el registro. Considera crear un EPIC dedicado si afecta a muchos proyectos.

P: Puedo propagar a solo algunos proyectos?

R: Si. Puedes marcar destinos como "descartado" con razon_descarte explicando por que no aplica a ese proyecto.

P: Quien decide si una mejora se propaga?

R: El desarrollador que hace la mejora inicia el proceso. El responsable de cada proyecto destino decide si aplica o descarta.

P: Que pasa si un proyecto no quiere recibir la propagacion?

R: Se marca como "descartado" con la razon. Esto se documenta para futuras referencias.

P: Con que frecuencia debo ejecutar check-module-versions.sh?

R: Recomendado: semanalmente o como parte del proceso de CI/CD.

P: Como se que modulos son los mas importantes de mantener actualizados?

R: Los modulos con tipo security-fix siempre tienen prioridad. Ejecuta el reporte para ver estado general.

---

Archivos Clave

Archivo	Proposito
CATALOGO-MODULOS.yml	Lista maestra de modulos disponibles
TRAZABILIDAD-PROYECTOS.yml	Mapeo modulo-proyecto con versiones
REGISTRO-PROPAGACIONES.yml	Historial de propagaciones
templates/TAREA-PROPAGACION.md	Template para tareas

---

Ver Tambien

• @PROPAGACION - Directiva oficial
• REGISTRO-PROPAGACIONES.yml - Historial
• TRAZABILIDAD-PROYECTOS.yml - Mapeo
• CATALOGO-MODULOS.yml - Lista de modulos

---

Creado: EPIC-007 Sistema: NEXUS v3.4