dtic-DIIAA/adn

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

# 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)

# 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.
7. Secretos en bóveda: NUNCA exponer contraseñas en texto plano. Usar candados (eval $(ruby adn/tools/seguridad/candados.rb load <clave>)).
8. Topología primero: Antes de conectarte a un nodo, consultar ./adn/tools/run contexto <nodo> para entender su ubicación en la red.
9. Exportación opcional: Los archivos .md son solo para archivo histórico. La operación real ocurre en PostgreSQL → Web.
10. Verificar en Web: Tras modificar la DB, acceder a http://localhost:5174 para verificar que los cambios se reflejan correctamente.
11. 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