127 lines
7.1 KiB
Markdown
127 lines
7.1 KiB
Markdown
# 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**: ...
|
|
```
|