dtic-DIIAA/adn/README.md

# ADN — Arquitectura de Datos y Normas (dtic-DIIAA)

> **DIRECTIVA PARA AGENTES IA**: Este archivo es tu punto de entrada obligatorio.
> Léelo COMPLETO antes de ejecutar cualquier acción sobre el repositorio.

## Identidad del Proyecto

| Clave            | Valor                                                              |
| :--------------- | :----------------------------------------------------------------- |
| **Nombre**       | dtic-DIIAA (Departamento de Investigación de IA y Automatización)  |
| **Repositorio**  | `/home/rmonla/Documentos/GitHub/dtic-DIIAA`                        |
| **Idioma**       | Español (TODO: docs, commits, comentarios, interacciones)          |
| **Lenguaje**     | Ruby (lenguaje de desarrollo para componentes y herramientas)      |
| **Filosofía**    | DB-First (Base de Datos PostgreSQL → Web)                         |
| **Zona Horaria** | `America/Argentina/Buenos_Aires` (UTC-3)                           |
| **Red remota**   | **Tailscale** (Cuenta: `pcdasu0@frlr.utn.edu.ar`)                  |

---

## Desarrollo y Registro de Actividades

### Lenguaje de Desarrollo: Ruby
- **Ruby es el lenguaje estándar** para todos los componentes, scripts y herramientas del proyecto.
- **Justificación**: Manejo robusto de excepciones, escalabilidad estructural y consistencia frente a la fragilidad de Bash para secuencias complejas.
- **Alcance**: Scripts de automatización (`tools/`), procesadores de respaldos, utilidades de gestión y cualquier lógica operativa recurrente.
- **Excepción**: Bash se permite únicamente para one-liners, wrappers de lanzamiento y tareas triviales de sistema donde Ruby introduzca complejidad innecesaria.

### Filosofía DB-First (Base de Datos PostgreSQL → Web)
**El sistema sigue una arquitectura DB-First donde PostgreSQL es la fuente de verdad única:**

1. **Base de Datos como Fuente Primaria**: Todas las bitácoras, eventos, nodos y proyectos se almacenan primero en PostgreSQL.
2. **Web como Interfaz**: La capa web (API Node.js + Frontend Vite) consume datos directamente de la base de datos.
3. **Sin Duplicación MD**: Los archivos `.md` son exportaciones secundarias, no fuentes primarias (evitar el anti-patrón MD-First).
4. **Validador Obsoleto**: La herramienta `validador` está en desuso por estar orientada a validación de archivos `.md` en lugar de validación de coherencia en la base de datos.

### Registro en Bitácora (DB-First)
**Toda actividad de desarrollo DEBE registrarse directamente en la base de datos PostgreSQL:**

1. **Auto-Registro Obligatorio**: Cualquier trabajo en componentes, scripts o herramientas Ruby debe registrarse como entrada en la bitácora del día usando `db evento:crear`.
2. **Formato DB-First**: Usar exclusivamente los subcomandos `db` de `./adn/tools/run` para operaciones CRUD.
3. **Trazabilidad en DB**: Cada modificación queda documentada en PostgreSQL con:
   - Contexto del cambio (qué componente y por qué)
   - Estado (✅ completado, ⏳ en proceso, ❌ fallido)
   - Métricas híbridas (tiempo invertido)
   - Relaciones con nodos y proyectos
4. **Exportación Opcional**: La exportación a Markdown es opcional y solo para archivo histórico, no para operación.

### Flujo de Trabajo DB-First
1. **Iniciar jornada**: `./adn/tools/run jornada iniciar [modo] [HH:MM]` (registra en DB)
2. **Registrar actividad**: `./adn/tools/run db evento:crear [opciones]` (estado y modo se calculan automáticamente)
3. **Desarrollar componente Ruby**: Seguir principios "Menos es Más" (atómico, reutilizable)
4. **Operaciones DB**: Usar `./adn/tools/run db` para todas las operaciones (listar, actualizar, eliminar)
5. **Registrar finalización**: `./adn/tools/run db evento:actualizar <ID> --fin HH:MM` (estado se calcula automáticamente)
6. **Verificar en Web**: Acceder a `http://localhost:5174` - La bitácora se actualiza automáticamente cada 30s o al recuperar el foco
7. **Resguardar cambios**: Commit y push con formato `[Categoría] Descripción`

### Subcomandos DB Disponibles
```bash
# Salud de la base de datos
./adn/tools/run db salud:bd

./adn/tools/run db evento:crear --nodo <nodo> --descripcion "..." [--plantilla <tipo>]
./adn/tools/run db evento:listar [--desde FECHA] [--hasta FECHA] [--nodo NODO] [--ambito AMBITO] [--detalle]
./adn/tools/run db evento:actualizar <ID> [--fin HH:MM] [--descripcion "..."]  # Estado ✅ se calcula automáticamente con --fin
./adn/tools/run db evento:eliminar <ID>

# Gestión de ámbitos (agrupadores de nodos)
./adn/tools/run db ámbito:crear --nombre <nombre> [--descripcion "texto"] [--parent-id <id>]
./adn/tools/run db ámbito:listar
./adn/tools/run db ámbito:nodos <nombre>

# Gestión de nodos
./adn/tools/run db nodo:crear --nombre <nombre> --tipo <tipo> [--ambito <nombre_o_id>]
./adn/tools/run db nodo:listar [--tipo TIPO] [--ambito AMBITO]

# Estadísticas
./adn/tools/run db estadisticas [--ambito AMBITO]
```

---

## Principios Rectores del ADN

### Tríptico Rector
Los tres principios que rigen toda decisión operativa del proyecto son:

1. **Menos es Más (Simplicidad Radical)**: Cada componente debe justificar su existencia y ser atómico y reutilizable. Preferir herramientas unificadas sobre scripts temporales, eliminar duplicaciones y consolidar funcionalidades dispersas. Los componentes deben diseñarse como piezas modulares que puedan ser reutilizadas por otros, evitando monolitos hardcodeados y promoviendo la composición sobre la duplicación.

2. **Armonía Integral**: El ADN, las Bitácoras, los Nodos y los Proyectos forman un organismo interconectado. La coherencia es un requisito de supervivencia.

3. **Mejora Continua (Evolución Progresiva)**: El ADN no es estático; evoluciona a partir de descubrimientos y buenas prácticas emergentes de la operación diaria.

### Principio Rector: Armonía Integral

**Si un dato cambia en un sitio, DEBE propagarse a todos los demás.**

El ADN, las Bitácoras, los Nodos y los Proyectos forman un organismo interconectado.
Ante cualquier inconsistencia detectada, **resolverla es prioritario antes de avanzar**.

---

## Estructura del Directorio `adn/`

```
adn/
├── README.md              ← ESTE ARCHIVO (punto de entrada IA)
├── 00_indice.md           ← Mapa general del ADN y tabla de bitácoras
├── 01_ontologia.md        ← Definición de nodos, servicios y topología de red
├── 02_bitacora.md         ← Formato del registro diario y reglas de triggers
├── 03_seguridad.md        ← Protocolos de seguridad, bóveda y secretos
├── 04_iconografia.md      ← Taxonomía visual: iconos semánticos para estados
├── 05_ia.md               ← ⚠️ FUENTE ÚNICA DE VERDAD para premisas IA
├── 06_gobernanza.md       ← Nomenclatura, codificación, armonía y evolución
├── 07_proyectos.md        ← Gestión transversal de proyectos e hitos
├── triggers.yml           ← Configuración del motor de triggers (propagación)
├── conocimiento/          ← Base de conocimiento asimilado
│   └── configuracion_bd.md
└── tools/                 ← Motor de ejecución y automatización (ver abajo)
```

Las hebras `01` a `07` son documentos normativos vivos. La hebra `05_ia.md` es la
referencia canónica y exclusiva de las directivas que un agente IA debe seguir.

---

## Herramienta CLI: `adn/tools/run`

> **REGLA DB-FIRST**: Antes de crear scripts temporales o ejecutar SQL directo,
> busca si ya existe un subcomando `db` que haga lo que necesitas.

**Punto de entrada**: `./adn/tools/run <subcomando> [opciones]`

### Subcomandos Disponibles (DB-First)

| Subcomando                            | Descripción                                      | Filosofía           |
| :------------------------------------ | :----------------------------------------------- | :------------------ |
| `db <subcomando>`                     | **Operaciones DB-First** (fuente de verdad)      | PostgreSQL Primario |
| `jornada iniciar [modo] [HH:MM]`     | Registrar inicio de jornada laboral en DB        | DB-First            |
| `jornada cerrar [modo] [HH:MM]`      | Registrar cierre de jornada laboral en DB        | DB-First            |
| `jornada estado`                      | Ver estado de la jornada actual desde DB         | DB-First            |
| `contexto <nodo> [--cmd]`             | Obtener contexto topológico y SSH de un nodo     | Consulta DB         |
| `nodos info <nodo>`                   | Mostrar metadata completa de un nodo (IP, SSH, auth) | Consulta Fichas     |
| `nodos agrupar [--servidor SRV]`      | Agrupar VMs por servidor anfitrión               | Consulta Fichas     |
| `nodos listar [--tipo TIPO]`          | Listar nodos desde fichas                        | Consulta Fichas     |
| `nodos buscar <término>`              | Buscar nodos por nombre o contenido              | Consulta Fichas     |
| `salud [--dashboard] [--json]`        | Ver salud general del sistema ADN                | Incluye DB          |
| `backup <nodo> [--mode MODO]`         | Ejecutar backup seguro de un nodo                | Registra en DB      |
| `triggers [--listar/--registrar]`     | Gestión del motor de triggers                    | Sincroniza DB       |
| `plan [subcomando]`                   | Gestión de planes y progreso de proyectos        | DB-First            |
| `estados`                             | Listar tareas en proceso (⏳) desde DB           | DB-First            |
| `proceso <nombre>`                    | Ejecutar procesos técnicos automatizados         | Registra en DB      |
| `generar bitacora [fecha]`            | Generar nueva bitácora en DB (YYYY-MM-DD)        | DB-First            |
| `generar nodo <nombre>`               | Generar ficha de nodo en DB                      | DB-First            |
| `generar proyecto <código>`           | Generar manifiesto de proyecto en DB             | DB-First            |
| `conocimiento asimilar <archivo>`     | Asimilar documentación al ADN                    | Almacena en DB      |
| `msp <subcomando>`                    | Gestión de MSPs NotebookLM (auditar, registrar, listar) | Integración MCP |
| `ssh <nodo> <comando>`                | Ejecución remota segura via SSH + Candados (lee fichas) | Via NodosInfo   |
| `ssh --listar`                        | Listar nodos con SSH configurado                 | Consulta Fichas     |
| `ayuda [subcomando]`                  | Mostrar ayuda detallada                          | -                   |
| `validador [--watch] [--fix]`         | ⚠️ **OBSOLETO** - Validación MD-First antigua    | MD-First (evitar)   |

### Subcomandos de Base de Datos (`db`) - Fuente de Verdad

| Subcomando                | Descripción                                    | Filosofía           |
| :------------------------ | :--------------------------------------------- | :------------------ |
| `db salud:bd`             | Verificar conexión y estado de PostgreSQL       | DB-First            |
| `db bitacora:crear`       | Crear nueva bitácora diaria en DB               | DB-First            |
| `db bitacora:listar`      | Listar bitácoras existentes desde DB            | DB-First            |
| `db evento:crear`         | Crear entrada (estado y modo se calculan auto.) | DB-First            |
| `db evento:listar`        | Listar entradas con filtros desde DB            | DB-First            |
| `db evento:actualizar`    | Actualizar entrada (estado auto. si --fin)      | DB-First            |
| `db evento:eliminar`      | Eliminar una entrada existente por ID de DB     | DB-First            |
| `db nodo:crear`           | Crear nuevo nodo en DB                          | DB-First            |
| `db nodo:listar`          | Listar nodos desde DB                           | DB-First            |
| `db estadisticas`         | Mostrar estadísticas del sistema desde DB       | DB-First            |
| `db hito:crear`           | Crear nuevo hito de proyecto en DB              | DB-First            |
| `db hito:listar`          | Listar hitos desde DB                           | DB-First            |
| `db migrar:md [fecha]`    | Migrar bitácora .md legacy a DB (una vez)       | Migración           |
| `db archivar:md`          | Mover archivos .md migrados al histórico        | Limpieza            |

### Ejemplos Frecuentes (DB-First)

```bash
# 1. INICIO DE JORNADA (registra en DB)
./adn/tools/run jornada iniciar presencial 08:00

# 2. REGISTRAR ACTIVIDAD (estado y modo se calculan automáticamente)
./adn/tools/run db evento:crear --nodo srv-ns8 --descripcion "Mejora del hook pre-commit" --inicio 09:00

# 2a. Con hora de fin (estado será ✅ automáticamente)
./adn/tools/run db evento:crear --nodo srv-ns8 --descripcion "Tarea completada" --inicio 09:00 --fin 10:00

# 3. LISTAR ACTIVIDADES DEL DÍA (consulta DB)
./adn/tools/run db evento:listar --desde $(date +%Y-%m-%d)

# 4. ACTUALIZAR ENTRADA AL FINALIZAR (estado se calcula desde --fin)
./adn/tools/run db evento:actualizar <ID> --fin 12:30

# 5. CERRAR JORNADA (registra en DB)
./adn/tools/run jornada cerrar remoto 18:00

# 6. VER ESTADO ACTUAL (desde DB)
./adn/tools/run jornada estado

# 7. LISTAR NODOS DESDE BASE DE DATOS
./adn/tools/run db nodo:listar --tipo srvv

# 8. BUSCAR NODOS EN DB
./adn/tools/run nodos buscar dasuten

# 9. VER SALUD DEL SISTEMA (incluye DB)
./adn/tools/run salud --dashboard

# 10. BACKUP CON REGISTRO EN DB
./adn/tools/run backup sql-dasuten

# 11. VER ESTADÍSTICAS DEL SISTEMA
./adn/tools/run db estadisticas

# 12. AUDITAR MSPs (NotebookLM)
./adn/tools/run msp auditar

# 13. LISTAR MSPs DISPONIBLES
./adn/tools/run msp listar

# 14. ACCEDER A INTERFAZ WEB (DB → Web)
# http://localhost:5174 (Frontend Vite)
# http://localhost:3002 (API Node.js)
```

---


## Directivas Críticas para IA (Actualizado DB-First)

1. **DB-First es obligatorio**: PostgreSQL es la fuente de verdad única. NUNCA operar sobre archivos `.md` como fuente primaria.
2. **Usar subcomandos `db`**: Para cualquier operación CRUD, usar `./adn/tools/run db <subcomando>`.
3. **Auto-Registro en DB**: Toda acción autónoma de la IA DEBE registrarse como entrada en la bitácora del día usando `db evento:crear`.
4. **Ruby como lenguaje de desarrollo**: Todos los componentes nuevos deben escribirse en Ruby, siguiendo principios "Menos es Más" (atómicos, reutilizables).
5. **Reutilizar submódulos CLI**: Antes de crear nueva lógica, verificar si existe submódulo en `cli/<comando>/` (ej: `nodos/info.rb`, `ssh/ejecutor.rb`). Duplicar código está prohibido. Infraestructura genuina vive en `core/` (colores, constants, logger, error_handler).
6. **Validador obsoleto**: NO usar `validador` (orientado a MD-First). En su lugar, validar coherencia mediante consultas a la base de datos.
6. **Secretos en bóveda**: NUNCA exponer contraseñas en texto plano. Usar `candados` (`eval $(ruby adn/tools/seguridad/candados.rb load <clave>)`).
7. **Topología primero**: Antes de conectarte a un nodo, consultar `./adn/tools/run contexto <nodo>` para entender su ubicación en la red.
8. **Exportación opcional**: Los archivos `.md` son solo para archivo histórico. La operación real ocurre en PostgreSQL → Web.
9. **Verificar en Web**: Tras modificar la DB, acceder a `http://localhost:5174` para verificar que los cambios se reflejan correctamente.
10. **Zona horaria**: Siempre `America/Argentina/Buenos_Aires`. Ya configurada en herramientas y contenedores Docker.

---

## Estructura de tools/

```
adn/tools/
├── run                    ← Entry point CLI (ejecutable Ruby)
├── cli/                   ← Subcomandos CLI (1 archivo + submódulos por comando)
│   ├── ayuda.rb           ← Documentación interna de la herramienta
│   ├── backup.rb          ← Backup seguro de nodos
│   │   └── backup/configurador.rb ← Carga de configuración YAML
│   ├── conocimiento.rb    ← Asimilación de documentación
│   ├── contexto.rb        ← Contexto topológico de nodos (usa nodos/info)
│   ├── db.rb              ← Dispatcher de subcomandos DB
│   │   └── db/             ← Subcomandos DB (evento, bitacora, nodo, etc.)
│   ├── estados.rb         ← Tareas en proceso (⏳) desde DB
│   ├── generar.rb         ← Generación de bitácoras, nodos y proyectos
│   ├── jornada.rb         ← Inicio/cierre de jornada (DB-First)
│   ├── msp.rb             ← Gestión de MSPs NotebookLM
│   ├── nodos.rb           ← Gestión de nodos (info, listar, agrupar, buscar)
│   │   └── nodos/info.rb  ← Extracción de metadata de fichas .md
│   ├── plan.rb            ← Gestión de planes y progreso
│   ├── proceso.rb         ← Procesos técnicos automatizados
│   ├── salud.rb           ← Métricas de salud del ADN
│   ├── ssh.rb             ← Ejecución remota segura via SSH + Candados
│   │   └── ssh/ejecutor.rb ← Abstracción de ejecución remota
│   ├── tailscale.rb       ← Gestión de Tailscale (nodos, status)
│   ├── triggers.rb        ← Gestión del motor de triggers
│   │   ├── triggers/motor.rb   ← Motor de triggers (reacción automática)
│   │   └── triggers/eventos.rb ← Bus de eventos (pub/sub desacoplado)
│   └── validador.rb       ← ⚠️ OBSOLETO (MD-First)
├── core/                  ← Infraestructura genuina (solo utilidades compartidas)
│   ├── colores.rb         ← Constantes de color para terminal
│   ├── conciliador.rb     ← Saneamiento preventivo de pendientes
│   ├── constants.rb       ← Constantes globales (rutas, estados)
│   ├── error_handler.rb   ← Helper para mensajes de error estandarizados
│   ├── help_formatter.rb  ← Formateador de ayuda estandarizado
│   └── logger.rb          ← Logger estructurado (JSON)
├── db/                    ← Capa de acceso a datos (PostgreSQL)
│   ├── core/              ← bitacora_db.rb (CRUD principal), buscadores
│   ├── cli/               ← Scripts CLI para exportación masiva
│   ├── exporters/         ← md_exporter.rb (DB → Markdown)
│   └── importers/         ← Importadores (Markdown → DB)
├── config/                ← Configuración
│   ├── database.yml       ← Conexión PostgreSQL (puerto 5433)
│   └── config.yml         ← Configuración general
├── hooks/                 ← Git hooks (pre-commit)
├── parsers/               ← Parsers especializados (plan.rb)
├── seguridad/             ← candados (gestión de secretos)
└── sondas/                ← Sondas remotas (w-zombi)
```

---

## Base de Datos (PostgreSQL)

| Clave        | Valor                          |
| :----------- | :----------------------------- |
| **Host**     | `localhost`                    |
| **Puerto**   | `5433` (Docker → 5432 interno) |
| **Database** | `dtic_bitacoras`               |
| **Schema**   | `bitacoras`                    |
| **Config**   | `adn/tools/config/database.yml`|

### Tablas Principales (schema `bitacoras`)

| Tabla       | Descripción                                           |
| :---------- | :---------------------------------------------------- |
| `nodos`     | Servidores, VMs, PCs, servicios del sistema           |
| `bitacoras` | Bitácoras diarias (fecha única por registro)           |
| `entradas`  | Entradas cronológicas en formato I-F-D-E              |
| `temas`     | Agrupadores de entradas por nodo                      |
| `gestion`   | Items de control de gestión (pendientes, en proceso)  |
| `proyectos` | Proyectos transversales                               |
| `fases`     | Fases de los proyectos                                |
| `hitos`     | Hitos individuales de cada fase                       |

### Docker Compose

Ubicación: `servicios/nginx/dtic-bitacoras/docker-compose.yml`
Servicios: `postgres` (BD), `api` (Node.js, puerto 3002), `frontend` (Vite, puerto 5174).

---

## Directorios del Repositorio

| Directorio       | Propósito                                              |
| :--------------- | :----------------------------------------------------- |
| `adn/`           | Núcleo genético: hebras, herramientas, conocimiento    |
| `nodos/`         | Fichas técnicas de cada nodo (1 archivo .md por nodo)  |
| `docs/bitacoras/`| Bitácoras diarias exportadas en Markdown               |
| `docs/proyectos/`| Manifiestos de proyectos                               |
| `docs/plan/`     | Planes de mejora y arquitectura                        |
| `servicios/`     | Docker Compose y configs de servicios (nginx, etc.)    |
| `logs/`          | Logs estructurados del sistema ADN                     |
| `automatizacion/`| Scripts legacy (en proceso de migración a adn/tools)   |

---

## Notas de Migración (MD-First → DB-First)

### Componentes Obsoletos (MD-First)
- **`validador`**: Herramienta para validar archivos `.md` - en desuso
- **`md_exporter.rb`**: Exportador DB → MD - uso solo para archivo histórico
- **Hooks pre-commit MD**: En proceso de migración a validación de coherencia DB

### Componentes Actuales (DB-First)
- **`./adn/tools/run db`**: Subcomandos CRUD para PostgreSQL
- **API Node.js (puerto 3002)**: Interfaz REST para operaciones DB
- **Frontend Vite (puerto 5174)**: Interfaz web que consume API
- **Docker Compose**: Contenedores PostgreSQL + API + Frontend

### Flujo de Migración Completo
1. **Fase 1**: Operación híbrida (MD + DB) - **COMPLETADO**
2. **Fase 2**: DB como fuente primaria, MD como histórico - **ACTUAL**
3. **Fase 3**: Eliminación completa de dependencias MD-First - **PLANIFICADO**

### Buenas Prácticas Actuales
1. **Siempre comenzar con `db evento:crear`** antes de cualquier trabajo
2. **Usar `db evento:actualizar`** al finalizar para registrar métricas
3. **Consultar `db evento:listar`** para ver estado actual
4. **Verificar en `http://localhost:5174`** para confirmar cambios
5. **Usar `jornada iniciar/cerrar`** para gestión de tiempo de trabajo