# DEVELOPMENT_FLOW.md — Flujo de Desarrollo del Organismo 4GatosCoin

Este documento define el flujo de trabajo oficial para contribuir al organismo 4GatosCoin.  
Incluye estándares, pasos, buenas prácticas, estructura de ramas, validaciones y reglas para mantener la coherencia técnica y narrativa del ecosistema.

---

# 1. Principios del Desarrollo

El desarrollo del organismo sigue estos principios:

- **Modularidad**: cada órgano vive en su propio módulo.  
- **No duplicación**: nunca duplicar lógica entre frontend y backend.  
- **Secuencialidad**: cada cambio se hace paso a paso.  
- **Trazabilidad**: todo evento debe quedar registrado.  
- **Narrativa viva**: cada cambio debe respetar la mitología del organismo.  
- **Seguridad**: nunca tocar producción sin confirmar variables y conexiones.  

---

# 2. Estructura de Ramas

```
main        → producción
develop     → integración
feature/*   → nuevas funciones
fix/*       → correcciones
sandbox/*   → experimentación
```

### 2.1. main
- solo merges aprobados  
- solo código estable  
- conectado a producción  

### 2.2. develop
- integración continua  
- pruebas internas  
- staging  

### 2.3. feature/*
- un órgano por rama  
- un cambio por rama  
- nunca mezclar sistemas  

### 2.4. fix/*
- correcciones puntuales  
- impacto mínimo  

### 2.5. sandbox/*
- experimentación  
- simulaciones  
- prototipos  

---

# 3. Flujo de Trabajo

```
feature → tests → logs → narrativa → merge → deploy
```

### 3.1. Crear rama
```
git checkout -b feature/nombre-del-organo
```

### 3.2. Implementar cambios
- añadir lógica en `lib/`  
- añadir modelos en `models/`  
- añadir endpoints en `app/api/`  
- añadir UI en `app/devweb3/`  

### 3.3. Añadir logs
Cada acción debe generar un log:

```
lib/logs/registerLog.ts
```

### 3.4. Añadir narrativa (si aplica)
Si el cambio afecta narrativa:

```
lib/narrative/
```

### 3.5. Añadir tests
```
tests/<organo>.test.ts
```

### 3.6. Crear PR
- descripción clara  
- impacto en órganos  
- impacto en narrativa  
- impacto en estado global  

### 3.7. Revisión
- coherencia técnica  
- coherencia narrativa  
- coherencia con el organismo  

### 3.8. Merge a develop
- pruebas en staging  
- validación de sandbox  

### 3.9. Deploy a main
- confirmar variables  
- confirmar backend  
- confirmar estado global  

---

# 4. Reglas de Contribución

### 4.1. Nunca duplicar lógica
- si algo existe en backend, no repetir en frontend  
- si algo existe en lib, no repetir en api  

### 4.2. Nunca mezclar órganos
Cada PR debe afectar **un solo órgano**.

### 4.3. Nunca romper narrativa
Si un cambio afecta narrativa, actualizar:

```
NARRATIVE_ENGINE.md
MEMORY_SYSTEM.md
SEASONS.md
```

### 4.4. Nunca romper estado global
Si un cambio afecta estado global, actualizar:

```
GLOBAL_STATE.md
```

### 4.5. Nunca tocar producción sin confirmar:
- `MONGODB_URI`  
- conexión backend  
- rutas API  
- sincronización de órganos  

---

# 5. Validaciones Antes de Merge

| Validación | Descripción |
|-----------|-------------|
| Tests | todos deben pasar |
| Logs | todos los eventos deben registrarse |
| Narrativa | coherencia con el motor narrativo |
| Estado Global | sin inconsistencias |
| Seguridad | sin riesgos |
| Documentación | actualizada |

---

# 6. Flujo de Deploy

```
develop → staging → validación → main → producción
```

### 6.1. Staging
- pruebas de energía  
- pruebas de gestos  
- pruebas de ciclos  
- pruebas de semillas  
- pruebas de narrativa  
- pruebas de OTT  

### 6.2. Producción
- confirmar variables  
- confirmar backend  
- confirmar sincronización  

---

# 7. Sandbox en el Flujo

El Sandbox se usa para:

- probar gestos  
- probar energía  
- probar ciclos  
- probar temporadas  
- probar rituales  
- probar narrativa  
- probar territorio  

Nunca afecta producción.

---

# 8. Checklist para Contributors

- [ ] rama creada correctamente  
- [ ] órgano aislado  
- [ ] lógica en lib  
- [ ] endpoints en api  
- [ ] UI en devweb3  
- [ ] logs añadidos  
- [ ] narrativa añadida  
- [ ] tests creados  
- [ ] documentación actualizada  
- [ ] PR limpio  
- [ ] merge seguro  

---

# 9. Roadmap del Flujo de Desarrollo

- CI/CD completo  
- tests narrativos  
- tests de territorio  
- tests de temporadas  
- simulación automática en sandbox  
- validación de narrativa generativa  

---

# 10. Licencia
Proyecto interno.  
Acceso restringido a desarrolladores autorizados.