# 🧬 ADN Tools (Núcleo Autónomo)

## Resumen Ejecutivo
`adn/tools` es el motor de ejecución y automatización del sistema **ADN (Artificial DNA)**. Implementa la lógica necesaria para garantizar la "Armonía Integral" de la infraestructura mediante validación proactiva, gestión de eventos y protocolos de ejecución autónomos. Actúa como el puente técnico entre las especificaciones declarativas (hebras `.md`) y la realidad operativa del servidor.

---

## 🔍 Análisis Estructural

### Arquitectura
El proyecto sigue un patrón **Modular y Dirigido por Eventos**:
- **Entry Point**: `adn/tools.rb` centraliza la interfaz de línea de comandos (CLI).
- **Bus de Eventos**: `ADN::Eventos` (Singleton) gestiona la comunicación desacoplada entre componentes.
- **Motor de Triggers**: `ADN::Triggers` (Singleton) orquestra acciones automáticas basadas en la configuración de `adn/triggers.yml`.
- **Estrategia de Subcomandos**: Cada funcionalidad mayor reside en su propio archivo `subcomando_*.rb`, facilitando la extensibilidad.

### Archivos Críticos
1.  **`adn.rb`**: El orquestador principal. Si este falla, se pierde la interfaz de gestión.
2.  **`adn/eventos.rb`**: El "sistema nervioso". Permite que un cambio en una bitácora dispare validaciones o backups.
3.  **`adn/validador.rb`**: El "guardián" de la calidad. Protege la integridad de las bitácoras y fichas de nodos.
4.  **`adn/triggers.rb`**: Implementa la lógica de reacción del sistema.

---

## ⚙️ Configuración y Tecnologías

### Stack Tecnológico
- **Lenguaje**: Ruby (Enfoque en scripting robusto y legible).
- **Configuración**: YAML (`adn/triggers.yml` y `adn/tools/config.yml`).
- **Logging**: JSON estructurado para integración con sistemas de monitoreo externos.
- **Hooks**: Integración con Git mediante `adn/tools/hooks/pre-commit`.

### Comandos Esenciales
```bash
# Validar cumplimiento de bitácoras
./adn/tools/run validador

# Ejecutar backup seguro de un nodo
./adn/tools/run backup <nombre-nodo>

# Ver salud del sistema
./adn/tools/run salud --json
```

---

## 🧠 Contexto para IA (Directivas)

### Convenciones Proyectuales
- **Singleton**: Los motores centrales (Eventos, Triggers, Logger) deben accederse siempre mediante su instancia única.
- **Bitácora-First**: Ninguna acción operativa debe ejecutarse sin antes registrarse en la bitácora del día actual.
- **Seguridad**: Nunca exponer secretos en `stdout`. Usar `ns8-candados run` para inyección de entorno.

### Áreas Delicadas / Deuda Técnica
- ⚠️ **Sincronización Batch**: El sistema de triggers utiliza `stubs` para muchas acciones de la Fase 2 que aún deben desarrollarse.
- ⚠️ **Modo Watch**: El validador en tiempo real (basado en `listen`) es una tarea pendiente de la Fase 1.
- ⚠️ **Métricas**: La extracción de telemetría desde las bitácoras es incipiente y requiere mayor robustez en el parser.

---

## 🚀 Próximos Pasos

### Tareas Prioritarias
1.  **Implementar Triggers**: Desarrollar la lógica real para las 14 acciones definidas en `adn/triggers.yml`.
2.  **Refinar `backup`**: Añadir soporte para protocolos XEN y Rclone dentro del subcomando unificado.
3.  **Dashboard de Salud**: Desarrollar la vista visual de `./adn/tools/run salud --dashboard`.

### Preguntas para el Desarrollador
- ¿Cómo se deben manejar las colisiones de eventos si dos triggers disparan acciones contradictorias?
- ¿Es necesario persistir el estado del bus de eventos o es puramente efímero?
- ¿Qué nivel de criticidad tiene el fallo de un trigger en la operación general?

---
*Documentación generada automáticamente siguiendo el estándar `docs/prompt/documentacion.md`.*