# 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 core/catalog/ o core/orchestration/ como fuente.     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

---

## CLASIFICACIÓN DE REFERENCIAS

### REFERENCIAS VÁLIDAS

| Tipo | Ejemplo | Uso Correcto |
|------|---------|--------------|
| **Core Catalog** | `core/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

```yaml
JERARQUÍA_VÁLIDA:

  Nivel_0_Core:
    - core/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

```yaml
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

```bash
# 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"

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

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

### Caso 2: Ruta a Otro Proyecto

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

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

### Caso 3: Lista de Proyectos de Referencia

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

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

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

### Caso 4: Directiva con Header de Proyecto

```yaml
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

```markdown
# 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

```yaml
# 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

```yaml
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

```markdown
| Funcionalidad | Origen |
| auth | Gamilit |

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

---

## INTEGRACIÓN CON SISTEMA SIMCO

### Al Inicializar Proyecto (SIMCO-INICIALIZACION)

```yaml
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)

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

### En Delegaciones (SIMCO-DELEGACION)

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

---

## CHECKLIST DE AUDITORÍA

Para validar un proyecto completo:

```bash
#!/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:** `core/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