# 05 - Hebra: Directivas de la Inteligencia Artificial

> Referencia canónica: [`adn/00_indice.md`](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`](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`](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`](06_gobernanza.md) — **Fuente canónica de los 3 principios rectores**: Menos es Más, Armonía Integral y Mejora Continua.

### 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`](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:
```bash
./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**: ...
```