dtic-DIIAA/adn/05_ia.md

05 - Hebra: Directivas de la Inteligencia Artificial

Referencia canónica: adn/00_indice.md

⚠️ FUENTE ÚNICA DE VERDAD. Este archivo es la referencia canónica y exclusiva de las premisas de trabajo de la IA. Las bitácoras diarias no duplican estas reglas, solo referencian esta hebra.

Premisas de Trabajo

1. Orden Inverso

Lo más nuevo SIEMPRE arriba (Tabla Resumen, Secciones de Nodo e Hitos).

2. Narrativa y Estructura Jerárquica

• Resumen (Arriba): Narrativa integral y sintética, SIN TÍTULOS NI ESTADOS en el texto.
• Detalle (Abajo): Encabezado de Nodo (H3), Título de Hito (H4), párrafo descriptivo, y finalmente una tabla de cronología | Tiempo | Descripción |.

3. Formato de Tiempo

Usar formato [Icono] HH:MM (ej. ✅ 23:26). ESTRICTAMENTE PROHIBIDO usar el sufijo "hs" o " hs".

4. Estados y Triggers

Sincronización en cascada entre secciones de la bitácora. Ver hebra 02_bitacora.md, sección "Triggers".

5. Iconografía

Título Principal = Estado (ej. ✅, ⏳, ➡️). Eventos cronológicos = Emojis semánticos al inicio de la celda de tiempo. Ver hebra 04_iconografia.md.

5.1 Trazabilidad de Proyectos

Toda entrada que responda a un plan de proyecto formalizado DEBE llevar el código identificador al inicio de la descripción: [CODIGO] Detalle.... Esto vincula inequívocamente el registro diario con la documentación técnica en docs/proy/.

6. Armonía

Consultar y seguir siempre las normativas vivas del ADN. Ver hebra 06_gobernanza.md.

7. Auto-Registro IA

Las acciones autónomas de la IA (ej. comandos SSH, inyección de discos, escaneos) DEBEN registrarse explícitamente en la cronología como hitos propios (indicando "(IA)" en el título) para garantizar la trazabilidad total de la operación conjunta.

8. Auto-Documentación IA

La IA debe mantener esta hebra de forma autónoma, asegurando que refleje las reglas y directrices más actuales para su operación y la del operador humano.

9. Métricas Híbridas (Telemetría)

OBLIGATORIO. Cada hito o bloque de sincronización (SINC) debe registrar el esfuerzo:

• En proceso: Usar formato [Físico/Remoto: Iniciado HH:MM].
• Finalizado: Usar formato de duración [Físico/Remoto: H:MM hs].

10. Secretos Operativos

La IA NUNCA pedirá ni escribirá contraseñas en texto plano. Se consumirán de forma efímera mediante la bóveda. Ver hebra 03_seguridad.md.

11. Gestión de Artefactos y Temporales (Workspace Bounds)

Cualquier script efímero (Python, Bash, PowerShell) creado por la IA para asistir en configuraciones, DEBE guardarse exclusivamente en el directorio local tmp/ del repositorio del proyecto. Está ESTRICTAMENTE PROHIBIDO el uso de carpetas globales del OS anfitrión (como /tmp).

12. Principio Bitácora-First (Anticipación)

Todo hito mayor, prueba de concepto técnica o interacción de red iniciada por la IA debe ser documentado en un borrador ⏳ dentro de la Bitácora ANTES de ejecutar los comandos en la Terminal. Una vez que la validación finalice, actualizar dicha fila al estado ✅ o ❌.

13. Auto-Contextualización Geográfica y Topológica

Antes de iniciar escaneos, pruebas de red, o conexiones SSH a un nodo de un proyecto, la IA DEBE investigar autónomamente su ubicación en la topología (ej. leyendo los encuadres en nodos/ y proyectos/).

• Objetivo: Identificar si el nodo objetivo está en una subred aislada, detrás de un NAT, o si requiere un salto de red (ProxyJump) a través de un hypervisor anfitrión, previniendo errores ciegos y garantizando trazabilidad geográfica.

14. Protocolo Autónomo de Ejecución (P.A.E.)

Para tareas operativas complejas (ej. backups), la IA DEBE utilizar las herramientas unificadas (adn/tools/run) que ya integran la lógica de seguridad y registro:

1. Ejecución: Usar ./adn/tools/run backup [nodo].
2. Seguridad: La herramienta utilizará internamente candados run para no exponer secretos.
3. Bitácora: El registro en docs/bitacoras/YYYY-MM-DD.md es automático mediante la herramienta.
4. Validación: La herramienta valida el contexto técnico (VMID, Host IP) consultando las fichas del ADN.

15. Análisis de Red Estandarizado

Para obtener información de topología de red de forma consistente y evitar búsquedas exploratorias:

• Uso: ./adn/tools/run network show [--formato json|markdown|texto] [--proyecto CODIGO] [--nodo NOMBRE] [--detalle]

• Ejemplo: ./adn/tools/run network show --json para obtener topología en formato JSON

• Ejemplo: ./adn/tools/run network show --proyecto P2604 --nodo srv-ns8 --detalle para información específica

• Beneficio: Elimina la necesidad de usar ls, grep y cat de forma exploratoria sobre /nodos.

16. DB Hooks para Automatización de Triggers

El sistema ADN implementa DB Hooks en la capa de datos para automatizar sincronizaciones que anteriormente requerían triggers.yml:

• Hook de Proyectos P2604: Al crear o actualizar una entrada con etiqueta [P2604], el sistema verifica y actualiza automáticamente el manifiesto del proyecto relacionado.

• Ventaja: Elimina la necesidad de editar dos archivos distintos para la misma acción, reduciendo la dependencia de IA para tareas de sincronización.

• Implementación: Los hooks están en adn/tools/db/core/bitacora_db.rb y se ejecutan después de operaciones create_entrada y update_entrada.

17. Sensor de Mejora Continua

OBLIGATORIO. El sistema implementa detección automática de fricción operativa:

Ritual de Inicio: Al inicio de cada sesión o cambio de contexto mayor, consultar:

./adn/tools/run salud --mejoras --json

Patrones Detectados:

1. Conexiones DB excesivas: > 5 conexiones/minuto → Sugiere connection pooling
2. Comandos repetitivos: > 5 comandos similares → Sugiere automatización
3. Inconsistencias documento-DB: Entradas [P2604] sin actualización en proyectos

Acción: Si se detectan patrones, exponer al operador y proponer mejora antes de continuar.

Implementación: adn/tools/db/core/mejoras_sensor.rb

18. Plantillas de Escritura para Eventos

Para enriquecer los detalles de eventos con estructura consistente:

Uso: ./adn/tools/run generar evento <tipo>

Tipos con iconos:

Ícono	Tipo	Uso
🔧	implementacion	Implementación técnica
🔍	investigacion	Investigación/exploración
🛠️	resolucion	Resolución de incidentes
📝	documentacion	Documentación/corrección
✅	test	Pruebas/validación
🐛	debug	Depuración
📋	planificacion	Planificación
👥	reunion	Reuniones/comunicaciones

Objetivo: Mejorar trazabilidad y escaneo visual en bitácoras.

Formato estándar para eventos:

[PROY.COD] Título ✅

**Tipo de evento**
**Campo 1**: ...
**Campo 2**: ...