workspace-v1/core/orchestration/directivas/DIRECTIVA-REFERENCIAS-PROYECTOS.md

DIRECTIVA: Referencias Entre Proyectos

Versión: 1.0.0 Fecha: 2025-12-12 Tipo: Directiva Operativa - CUMPLIMIENTO OBLIGATORIO Aplica a: Todos los agentes, toda documentación de orchestration

---

PROBLEMA QUE RESUELVE

╔══════════════════════════════════════════════════════════════════════╗
║                                                                       ║
║   CADA PROYECTO DEBE SER INDEPENDIENTE Y AUTO-CONTENIDO              ║
║                                                                       ║
║   "Un proyecto NO debe depender de otro proyecto para funcionar."    ║
║   "Las referencias cruzadas generan acoplamiento y confusión."       ║
║                                                                       ║
╚══════════════════════════════════════════════════════════════════════╝

Síntomas del problema:

• Documentación con "Proyecto de referencia: X"
• Rutas hardcodeadas a otros proyectos (projects/gamilit/...)
• Directivas genéricas con nombres de proyectos específicos
• Prompts que referencian código de otros proyectos

---

REGLA FUNDAMENTAL

┌─────────────────────────────────────────────────────────────────────┐
│                                                                      │
│   NUNCA referenciar un proyecto desde otro proyecto.                │
│   SIEMPRE usar shared/catalog/ o core/orchestration/ como fuente.     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

CLASIFICACIÓN DE REFERENCIAS

REFERENCIAS VÁLIDAS

Tipo	Ejemplo	Uso Correcto
Core Catalog	shared/catalog/auth/	Componentes reutilizables
Core Orchestration	core/orchestration/directivas/	Directivas y templates
Subproyecto Interno	erp-suite/apps/erp-core/	Solo desde la misma suite
Ejemplos Ilustrativos	ejemplos: "gamilit, trading"	Solo como ilustración marcada
Histórico/Migración	"Se adaptaron patrones de X"	Documentación de decisiones

REFERENCIAS PROHIBIDAS

Tipo	Ejemplo	Por Qué Es Problema
"Proyecto de referencia"	Proyecto referencia: gamilit	Crea dependencia falsa
Rutas directas	projects/gamilit/apps/backend/	Acoplamiento entre proyectos
Headers específicos	**Proyecto:** GAMILIT en directiva genérica	Limita aplicabilidad
Importaciones	"copiar de projects/X"	Rompe independencia

---

JERARQUÍA DE DEPENDENCIAS PERMITIDA

JERARQUÍA_VÁLIDA:

  Nivel_0_Core:
    - shared/catalog/           # Funcionalidades reutilizables
    - core/orchestration/     # Directivas y templates
    - core/devtools/          # Herramientas de desarrollo

  Nivel_1_Proyecto:
    puede_depender_de:
      - Nivel_0_Core          # ✓ SIEMPRE PERMITIDO
    NO_puede_depender_de:
      - Otros proyectos       # ✗ PROHIBIDO

  Nivel_2_Subproyecto:
    puede_depender_de:
      - Nivel_0_Core          # ✓ PERMITIDO
      - Suite padre           # ✓ PERMITIDO (ej: vertical → erp-core)
    NO_puede_depender_de:
      - Otros proyectos       # ✗ PROHIBIDO
      - Otras suites          # ✗ PROHIBIDO

---

PROCEDIMIENTO DE VALIDACIÓN

Al Crear Documentación

CHECKLIST_CREACIÓN:
  - [ ] ¿La sección "Referencias" apunta solo a core/?
  - [ ] ¿NO existe línea "Proyecto de referencia"?
  - [ ] ¿Las rutas NO contienen "projects/{otro-proyecto}/"?
  - [ ] ¿Los ejemplos están claramente marcados como tales?
  - [ ] ¿El header NO tiene nombre de proyecto específico?

Al Revisar Documentación Existente

# Buscar referencias problemáticas
grep -r "Proyecto referencia" orchestration/
grep -r "projects/gamilit" orchestration/
grep -r "projects/trading" orchestration/
grep -r "projects/erp-suite" orchestration/  # Excepto si estás EN erp-suite

# Buscar rutas obsoletas
grep -r "workspace-gamilit" .

---

CÓMO CORREGIR REFERENCIAS PROBLEMÁTICAS

Caso 1: "Proyecto de Referencia"

ANTES:
  | Proyecto referencia | `/home/isem/workspace/projects/gamilit/` |

DESPUÉS:
  # ELIMINAR la línea completamente
  # O cambiar a:
  | Catálogo global | `/home/isem/workspace/shared/catalog/` |

Caso 2: Ruta a Otro Proyecto

ANTES:
  - Patrones auth: `projects/gamilit/apps/backend/src/auth/`

DESPUÉS:
  - Patrones auth: `shared/catalog/auth/`

Caso 3: Lista de Proyectos de Referencia

ANTES:
  ## Proyectos de Referencia
  | Proyecto | Path | Patrones |
  | Gamilit | projects/gamilit/ | Auth, RLS |

DESPUÉS:
  ## Patrones de Referencia (desde Catálogo)
  > **Nota:** Usar siempre shared/catalog/ para componentes reutilizables.

  | Patrón | Catálogo |
  | Auth | shared/catalog/auth/ |
  | RLS | shared/catalog/multi-tenancy/ |

Caso 4: Directiva con Header de Proyecto

ANTES:
  **Proyecto:** GAMILIT - Sistema de Gamificación

DESPUÉS:
  # Si es directiva específica del proyecto:
  **Proyecto:** {nombre del proyecto actual}

  # Si es directiva genérica (en core/):
  # ELIMINAR el header de proyecto

---

EXCEPCIONES PERMITIDAS

1. Documentación Histórica

# Migración de Supabase a Express
**Contexto histórico:** Se adaptaron patrones del proyecto Gamilit...

# ✓ VÁLIDO: Explica decisiones pasadas, no crea dependencia

2. Inventario de Puertos

# DEVENV-PORTS-INVENTORY.yml
projects:
  gamilit:
    range: "3000-3099"
  trading-platform:
    range: "3200-3299"

# ✓ VÁLIDO: Es inventario del workspace, no dependencia

3. Ejemplos Ilustrativos en SIMCO

NIVEL_2A_STANDALONE:
  ejemplos: "gamilit, trading-platform, betting-analytics"

# ✓ VÁLIDO: Claramente marcado como ejemplo, no como dependencia

4. Origen de Funcionalidades en Catálogo

| Funcionalidad | Origen |
| auth | Gamilit |

# ✓ VÁLIDO: Indica procedencia histórica en catálogo centralizado

---

INTEGRACIÓN CON SISTEMA SIMCO

Al Inicializar Proyecto (SIMCO-INICIALIZACION)

PASO_ADICIONAL:
  verificar_referencias:
    - Revisar CONTEXTO-PROYECTO.md generado
    - Confirmar que NO tiene "Proyecto de referencia"
    - Confirmar referencias apuntan a core/

Al Crear Documentación (SIMCO-DOCUMENTAR)

VALIDACIÓN_ADICIONAL:
  antes_de_commit:
    - grep "Proyecto referencia" {archivo}
    - grep "projects/{otro}" {archivo}
    - Si encuentra → CORREGIR antes de continuar

En Delegaciones (SIMCO-DELEGACION)

CONTEXTO_A_PASAR:
  referencias_permitidas:
    - shared/catalog/
    - core/orchestration/
    - {proyecto_actual}/  # Solo interno
  referencias_prohibidas:
    - projects/{otro}/

---

CHECKLIST DE AUDITORÍA

Para validar un proyecto completo:

#!/bin/bash
# audit-references.sh

PROJECT=$1
echo "=== Auditoría de Referencias: $PROJECT ==="

echo ""
echo "1. Buscando 'Proyecto referencia'..."
grep -rn "Proyecto referencia" "$PROJECT/orchestration/" && echo "  ⚠️ ENCONTRADO" || echo "  ✓ OK"

echo ""
echo "2. Buscando referencias a otros proyectos..."
for other in gamilit trading-platform erp-suite betting-analytics inmobiliaria-analytics platform_marketing_content; do
  if [ "$other" != "$(basename $PROJECT)" ]; then
    count=$(grep -rn "projects/$other" "$PROJECT/orchestration/" 2>/dev/null | wc -l)
    if [ $count -gt 0 ]; then
      echo "  ⚠️ $count referencias a $other"
    fi
  fi
done

echo ""
echo "3. Buscando rutas obsoletas..."
grep -rn "workspace-gamilit" "$PROJECT/" && echo "  ⚠️ ENCONTRADO" || echo "  ✓ OK"

echo ""
echo "=== Fin de Auditoría ==="

---

REFERENCIAS

• Principio relacionado: PRINCIPIO-ANTI-DUPLICACION.md
• Catálogo global: shared/catalog/
• Templates: core/orchestration/templates/
• Índice SIMCO: core/orchestration/directivas/simco/_INDEX.md

---

Versión: 1.0.0 | Sistema: SIMCO v3.2 | Mantenido por: Workspace Manager