# PROTOCOLO-COORDINACION.yml
# Define el flujo de coordinacion entre agentes para propagacion
# Version: 1.0.0
# Sistema: NEXUS v3.4 + SIMCO + CAPVED
# EPIC: EPIC-012
# Creado: 2026-01-04

metadata:
  version: "1.0.0"
  created: "2026-01-04"
  updated: "2026-01-04"
  descripcion: "Protocolo de coordinacion para propagacion de mejoras"
  sistema: "NEXUS v3.4 + SIMCO + CAPVED"

actores:
  - id: "desarrollador"
    descripcion: "Persona que detecta mejora propagable"

  - id: "@PERFIL_KB_MANAGER"
    descripcion: "Agente gestor de Knowledge-Base"

  - id: "@PERFIL_PROJECT_AGENT"
    descripcion: "Agente que ejecuta en proyecto destino"

  - id: "@PERFIL_INTEGRATION_VALIDATOR"
    descripcion: "Agente que valida integracion final"

flujo:
  - paso: 1
    nombre: "Deteccion de mejora"
    actor: "desarrollador"
    accion: "Detecta mejora propagable en proyecto X"
    artefactos_entrada: []
    artefactos_salida:
      - "Issue/Ticket de propagacion"
    notifica_a: "@PERFIL_KB_MANAGER"
    mediante: "Script propagate-module-update.sh o Issue manual"

  - paso: 2
    nombre: "Analisis CAPVED"
    actor: "@PERFIL_KB_MANAGER"
    accion: "Analiza mejora siguiendo proceso CAPVED"
    artefactos_entrada:
      - "Issue/Ticket"
      - "Codigo de mejora"
    artefactos_salida:
      - "ANALISIS-PROP-XXX.md"
    decision:
      tipo: "binaria"
      opciones:
        - "Propagar"
        - "No propagar (documentar razon)"
    criterios_decision:
      propagar_si:
        - "Mejora generica (no especifica de proyecto)"
        - "Afecta modulo en KB"
        - "Tiene tests"
        - "Es security-fix, bug-fix, o feature util"
      no_propagar_si:
        - "Cambio especifico del proyecto"
        - "No tiene tests"
        - "Breaking change sin migration guide"

  - paso: 3
    nombre: "Actualizacion Level 0 (core)"
    actor: "@PERFIL_KB_MANAGER"
    accion: "Actualizar modulo en shared/catalog si aplica"
    artefactos_entrada:
      - "ANALISIS-PROP-XXX.md"
      - "Codigo de mejora"
    artefactos_salida:
      - "Commit en shared/catalog"
    validacion: "Documentacion del modulo actualizada"
    condicional: "Solo si mejora afecta shared/catalog"

  - paso: 4
    nombre: "Actualizacion Level 1 (KB)"
    actor: "@PERFIL_KB_MANAGER"
    accion: "Sincronizar con shared/knowledge-base"
    artefactos_entrada:
      - "Cambios en shared/catalog"
    artefactos_salida:
      - "CATALOGO-MODULOS.yml actualizado"
      - "Commit en knowledge-base"
    validacion: "Version actualizada en catalogo"

  - paso: 5
    nombre: "Generacion de tareas SCRUM"
    actor: "@PERFIL_KB_MANAGER"
    accion: "Generar tareas formales para proyectos afectados"
    artefactos_entrada:
      - "TRAZABILIDAD-PROYECTOS.yml"
      - "NIVELES-PROPAGACION.yml"
    artefactos_salida:
      - "EPIC-PROP-XXX.md (si cambio grande)"
      - "TASK-PROP-XXX-{proyecto}.md (por proyecto)"
    herramienta: "generate-scrum-tasks.sh"
    notifica_a: "@PERFIL_PROJECT_AGENT (por proyecto)"

  - paso: 6
    nombre: "Ejecucion en proyecto"
    actor: "@PERFIL_PROJECT_AGENT"
    accion: "Ejecutar tarea de propagacion en proyecto destino"
    artefactos_entrada:
      - "TASK-PROP-XXX-{proyecto}.md"
    artefactos_salida:
      - "Commit en proyecto"
      - "Build exitoso"
      - "Tests pasando"
    validacion: "npm run build && npm test"
    reporta_a: "@PERFIL_KB_MANAGER"

  - paso: 7
    nombre: "Validacion integral"
    actor: "@PERFIL_KB_MANAGER"
    accion: "Validar integracion completa de propagacion"
    artefactos_entrada:
      - "Reportes de @PERFIL_PROJECT_AGENT"
    artefactos_salida:
      - "REGISTRO-PROPAGACIONES.yml actualizado"
      - "TRAZABILIDAD-PROYECTOS.yml actualizado"
      - "Propagacion cerrada"
    herramienta: "validate-propagation-chain.sh"
    checklist:
      - "Todas las tareas completadas"
      - "Versiones sincronizadas"
      - "HERENCIA-SIMCO.md actualizados"
      - "PROJECT-STATUS.md actualizados"

handoff:
  kb_manager_to_project:
    nombre: "Delegacion de tarea"
    canal: "Tarea SCRUM formal (TASK-PROP-XXX-{proyecto}.md)"
    contenido_requerido:
      - "Descripcion del cambio"
      - "Version origen y destino"
      - "Archivos afectados"
      - "Criterios de aceptacion"
      - "Referencia a @PROPAGACION"
      - "Pasos de implementacion"
    formato: "Markdown con YAML frontmatter"

  project_to_kb_manager:
    nombre: "Reporte de ejecucion"
    canal: "Actualizacion de tarea + commit"
    contenido_requerido:
      - "Estado (completado/fallido/bloqueado)"
      - "Commit hash"
      - "Notas de implementacion"
      - "Validaciones ejecutadas"
      - "Problemas encontrados (si hay)"
    formato: "Comentario en tarea o seccion EJECUCION"

escalacion:
  - condicion: "Tarea bloqueada por mas de 24h (security-fix)"
    accion: "Escalar a @PERFIL_TECH_LEADER"

  - condicion: "Breaking change sin migration guide"
    accion: "Devolver a @PERFIL_KB_MANAGER para crear guia"

  - condicion: "Tests fallan en proyecto destino"
    accion: "Colaborar @PERFIL_KB_MANAGER + @PERFIL_PROJECT_AGENT"

  - condicion: "Conflicto de versiones"
    accion: "Escalar a @PERFIL_ARCHITECTURE_ANALYST"

tiempos_objetivo:
  security_fix:
    analisis: "< 2 horas"
    propagacion_completa: "< 24 horas"
  bug_fix:
    analisis: "< 4 horas"
    propagacion_completa: "< 48 horas"
  feature:
    analisis: "< 1 dia"
    propagacion_completa: "< 1 semana"

referencias:
  - "@PROPAGACION: core/orchestration/directivas/simco/SIMCO-PROPAGACION-MEJORAS.md"
  - "@KB_MANAGER: core/orchestration/agents/perfiles/PERFIL-KB-MANAGER.md"
  - "@NIVELES: shared/knowledge-base/propagacion/NIVELES-PROPAGACION.yml"
  - "USAGE.md: shared/knowledge-base/propagacion/USAGE.md"