Files

T

Ricardo Monla 2b8c4a9916 [ADN] Actualización de principios rectores en README.md - Inclusión completa del Tríptico Rector

2026-03-12 05:30:32 -03:00

13 KiB

Raw Blame History

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 (scripts y herramientas operativas)
Zona Horaria	`America/Argentina/Buenos_Aires` (UTC-3)

Principios Rectores del ADN

Tríptico Rector

Los tres principios que rigen toda decisión operativa del proyecto son:

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.
Armonía Integral: El ADN, las Bitácoras, los Nodos y los Proyectos forman un organismo interconectado. La coherencia es un requisito de supervivencia.
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: Antes de crear scripts temporales o ejecutar SQL directo, busca si ya existe un subcomando que haga lo que necesitas.

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

Subcomandos Disponibles

Subcomando	Descripción
`validador [--watch] [--fix]`	Validar cumplimiento del ADN en bitácoras
`contexto <nodo> [--cmd]`	Obtener contexto topológico y SSH de un nodo
`nodos agrupar [--servidor SRV]`	Agrupar VMs por servidor anfitrión
`nodos listar [--tipo TIPO]`	Listar fichas de nodos (.md)
`nodos buscar <término>`	Buscar nodos por nombre o contenido
`jornada iniciar [modo] [HH:MM]`	Registrar inicio de jornada laboral
`jornada cerrar [modo] [HH:MM]`	Registrar cierre de jornada laboral
`jornada estado`	Ver estado de la jornada actual
`salud [--dashboard] [--json]`	Ver salud general del sistema ADN
`generar bitacora [fecha]`	Generar nueva bitácora (YYYY-MM-DD, default: hoy)
`generar nodo <nombre>`	Generar ficha de nodo
`generar proyecto <código>`	Generar manifiesto de proyecto
`conocimiento asimilar <archivo>`	Asimilar documentación al ADN
`backup <nodo> [--mode MODO]`	Ejecutar backup seguro de un nodo
`triggers [--listar/--registrar]`	Gestión del motor de triggers
`plan [subcomando]`	Gestión de planes y progreso de proyectos
`ayuda [subcomando]`	Mostrar ayuda detallada

Subcomandos de Base de Datos (`db`)

Subcomando	Descripción
`db salud:bd`	Verificar conexión y estado de PostgreSQL
`db bitacora:crear`	Crear nueva bitácora diaria en DB
`db bitacora:listar`	Listar bitácoras existentes
`db evento:crear`	Crear nueva entrada cronológica (I-F-D-E)
`db evento:listar`	Listar entradas con filtros (nodo, estado, fecha)
`db evento:actualizar`	Actualizar una entrada existente
`db evento:eliminar`	Eliminar una entrada existente por ID
`db nodo:crear`	Crear nuevo nodo (servidor/VM/PC/servicio)
`db nodo:listar`	Listar nodos del sistema
`db estadisticas`	Mostrar estadísticas del sistema
`db archivar:md`	Mover archivos .md migrados al archivo histórico

Ejemplos Frecuentes

# Inicio de jornada presencial a las 08:00
./adn/tools/run jornada iniciar presencial 08:00

# Cierre de jornada remota a las 23:00
./adn/tools/run jornada cerrar remoto 23:00

# Ver estado de la jornada actual
./adn/tools/run jornada estado

# Cerrar una entrada abierta
./adn/tools/run db evento:actualizar <ID> --fin 17:00

# Listar actividades de hoy
./adn/tools/run db evento:listar --desde $(date +%Y-%m-%d)

# Exportar bitácora a Markdown
ruby -I adn/tools/db -e 'require "core/bitacora_db"; require "exporters/md_exporter";
  db = BitacorasDB::BitacoraDB.new(config_path: "adn/tools/config/database.yml");
  db.connect; BitacorasDB::Exporters::MDExporter.new(db).exportar_bitacora("FECHA", "docs/bitacoras/FECHA.md")'

# Ver nodos agrupados por servidor
./adn/tools/run nodos agrupar

# Filtrar VMs de un servidor específico
./adn/tools/run nodos agrupar --servidor srv-pmox1

# Listar solo VMs de servicio
./adn/tools/run nodos listar --tipo srvv

# Buscar nodos relacionados con dasuten
./adn/tools/run nodos buscar dasuten

# Backup de un nodo
./adn/tools/run backup sql-dasuten

Estructura de tools/

adn/tools/
├── run                    ← Entry point CLI (ejecutable Ruby)
├── cli/                   ← Subcomandos CLI (1 archivo por subcomando)
│   ├── ayuda.rb           ← Documentación interna de la herramienta
│   ├── backup.rb          ← Backup seguro de nodos
│   ├── cierre.rb          ← Cierre de jornada (DB-First)
│   ├── conocimiento.rb    ← Asimilación de documentación
│   ├── contexto.rb        ← Contexto topológico de nodos
│   ├── db.rb              ← Dispatcher de subcomandos DB
│   ├── db/                ← Subcomandos específicos de DB (evento, bitacora, nodo, etc.)
│   ├── generar.rb         ← Generación de bitácoras, nodos y proyectos
│   ├── inicio.rb          ← Inicio de jornada (DB-First)
│   ├── nodos.rb           ← Agrupación de nodos por servidor
│   ├── plan.rb            ← Gestión de planes y progreso
│   ├── salud.rb           ← Métricas de salud del ADN
│   ├── triggers.rb        ← Gestión del motor de triggers
│   └── validador.rb       ← Validación de cumplimiento ADN
├── core/                  ← Módulos centrales (Singleton)
│   ├── colores.rb         ← Constantes de color para terminal
│   ├── conciliador.rb     ← Saneamiento preventivo de pendientes
│   ├── configurador.rb    ← Carga de configuración YAML
│   ├── eventos.rb         ← Bus de eventos (pub/sub desacoplado)
│   ├── logger.rb          ← Logger estructurado (JSON)
│   ├── triggers.rb        ← Motor de triggers (reacción automática)
│   └── validador.rb       ← Validador de formato ADN
├── 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/             ← ns8-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)

Directivas Críticas para IA

Usa las herramientas existentes: ./adn/tools/run tiene subcomandos para casi todo. NO crees scripts temporales en /tmp/ ni ejecutes SQL directo si existe un subcomando.
Fuente de verdad: 05_ia.md: Lee y sigue TODAS las premisas antes de operar.
DB-First: La base de datos PostgreSQL es la fuente de verdad para bitácoras y entradas. Los archivos .md se generan mediante exportación (md_exporter.rb).
Secretos: NUNCA exponer contraseñas en texto plano. Usar ns8-candados.
Auto-Registro: Toda acción autónoma de la IA DEBE registrarse como entrada en la bitácora del día usando db evento:crear.
Topología primero: Antes de conectarte a un nodo, consulta ./adn/tools/run contexto <nodo> para entender su ubicación en la red (subred, proxy jump, etc.).
Exportar al cerrar: Tras modificar entradas en la DB del día, regenerar el .md correspondiente con el exportador.
Zona horaria: Siempre America/Argentina/Buenos_Aires. Ya configurada en adn/tools/run y en los contenedores Docker.

13 KiB Raw Blame History