Files
dtic-DIIAA/adn/02_protocolo.md
T

10 KiB

02 - Protocolo del Proyecto: Normas y Directivas

Este documento establece las reglas fundamentales para la interacción, documentación y desarrollo en el proyecto srv-ns8.

1. Idioma y Nomenclatura

  • Directiva: Todo el contenido debe estar en español.
  • Nomenclatura de Nodos: Estrictamente minúsculas en nombres de archivo y referencias (ej: srv-ns8, pc-dasu0, srvv-maurik).
  • Alcance:
    • Interacciones con el asistente (chat).
    • Documentación (archivos .md).
    • Mensajes de Commit (Git).
    • Comentarios en el código (scripts, configs).

2. Formato de Documentación

  • Estilo: Markdown estándar.
  • Ubicación: Todo documento clave debe residir en el directorio adn/.

3. Armonía y Auto-optimización

  • Principio: La documentación (ADN) debe mantenerse como un todo coherente y libre de contradicciones.
  • Alcance Global: Esta directiva aplica a TODOS los directorios del proyecto, incluyendo adn/, bitacoras/, nodos/, y procedimientos/.
  • Directiva:
    • Consistencia: No deben existir discrepancias entre diferentes hebras. Si se actualiza una definición en 01_ontologia.md, debe reflejarse en los protocolos y bitácoras correspondientes.
    • Trazabilidad: Los IDs y estados deben ser consistentes a través del tiempo.
    • Auto-corrección: Al detectar una inconsistencia, es prioritario resolverla para restaurar la armonía del sistema documental.

4. Estructura de Bitácora (Flujo Diario)

  • Principio: Orden Inverso Cronológico (Lo más nuevo SIEMPRE ARRIBA).
  • Archivo Diario: bitacoras/YYYY-MM-DD.md.
  • Secciones Obligatorias:

4.1 Control de Gestión

  • Pendientes: Tabla de tareas por hacer (ID [Icono] - [Hora Ini] - [Nombre Tarea] | NODO | DETALLE).
  • En Proceso: Tabla de tareas activas (ID [Icono] - [Hora Ini] - [Nombre Tarea] | NODO | DETALLE).
  • Resumen de Actividades:
    • Formato: Tabla (NODO | RESUMEN INTEGRAL).
    • Estilo: Narrativa Sintética e Integral. SIN TÍTULOS NI ESTADOS en el texto. Solo la historia consolidada del día para ese nodo.
    • Regla: Una sola fila por Nodo.

4.2 Actividades Detalladas

  • Subdivisión: Encabezados por Nodo (### srv-ns8).
  • Formato Jerárquico:
    1. Título H4 del Tema: #### [Estado] - [ID] - [Nombre Tarea] (ej. #### ✅ - A09 - dtic-BKPs C4).
    2. Párrafo Narrativo: Descripción rica que incluye referencias de migración (ej. ➡️ **[Viene del 23/02]...**) y que explica el "qué" y el "por qué" de la tarea.
    3. Tabla Cronológica: Tabla | Tiempo | Descripción |.
  • Formato de Tiempo: La columna Tiempo debe usar la sintaxis [Icono Semántico] HH:MM SIN el sufijo "hs" (ej. ✅ 23:26).
    • Métricas Operativas (Dashboard): Para soportar la telemetría del dashboard de proyectos, las tareas que consumen tiempo prolongado (especialmente durante hitos de implementacion) deben especificar su esfuerzo en el texto usando las etiquetas [Físico: X hs] y/o [Remoto: Y hs]. La IA parseará estas etiquetas para alimentar los medidores duales (physical vs remote) en las líneas de tiempo web.
  • Estados (Tema): Estrictamente delimitados para trazabilidad (✅ Cerrado, ⏳ En Proceso, ⚠️ Fallo).
  • Semántica (General): Uso de una taxonomía visual rica tanto en el párrafo de descripción como en cada fila de cronograma para otorgar un escaneo visual ultrarrápido (ej. 🔧, 🧹, 📝, 🧪, 💾).
  • Auto-Registro (IA): El proyecto es operado de forma conjunta. Cualquier acción técnica, investigación subyacente o inyección de comandos SSH realizada autónomamente por la Inteligencia Artificial DEBE registrarse explícitamente en las tablas cronológicas (indicando "(IA)" y el respectivo emoji semántico), asegurando la trazabilidad absoluta de la autoría técnica de cada evento.

4.3 Reglas de Sincronización en Cascada (Triggers)

El mantenimiento de la bitácora es dinámico y reactivo. La actualización de una sección debe disparar (trigger) la actualización de sus dependencias para garantizar consistencia:

  • Trigger 1 (Detalle -> En Proceso): Al insertar una nueva viñeta en la cronología de Hitos de una tarea activa (⏳), se DEBE actualizar la columna DETALLE de esa misma tarea en la tabla En Proceso para reflejar su último estado de avance.
  • Trigger 2 (Cierre -> Resumen Integral): Al cambiar el estado de la última tarea activa de un Nodo de ⏳ a ✅ (o ⚠️), indicando que ya no quedan tareas en proceso para dicho nodo, se DEBE desencadenar la redacción o actualización de su RESUMEN INTEGRAL consolidado en la tabla de inicio.
  • Trigger 3 (Cambio de Día -> Rollover): Al crear un nuevo archivo de bitácora (YYYY-MM-DD.md):
      1. Heredar íntegro el bloque HTML final de Premisas de Trabajo (IA) de la bitácora de ayer.
      1. Migrar las actividades Pendientes y En Proceso hacia las tablas de Control de Gestión del nuevo día.
      1. En la bitácora del día fenecido, cambiar el Estado Tema de las tareas migradas de ⏳ (o 📍) a ➡️ (Migrado), y añadir una viñeta final de Hito narrando el traspaso (ej. - ➡️ **23:59 hs**: Tarea delegada a la bitácora de mañana.).
  • Al final de cada bitácora, incluir el bloque de comentarios HTML con las Premisas de Trabajo.
  • Evolución: El footer debe ser idéntico al del día anterior o una versión evolucionada (con nuevas reglas). NUNCA una versión simplificada o diferente.
  • Registro: Las nuevas reglas se acumulan para mantener la memoria del sistema.

5. Documentación de Nodos (Snapshots)

  • Ubicación: nodos/<hostname>.md (Raíz del proyecto).
  • Contenido: Representa el Estado Actual (Snapshot) del nodo.
  • Actualización: Solo se modifica cuando cambia la configuración o estado del nodo. No duplicar información dinámica de la bitácora.

6. Protocolo de Seguridad de Red (Hombre Muerto)

  • Problemática: La administración remota del servidor implica el riesgo de desconexión total ante cambios erróneos en la configuración de red.
  • Directiva: Toda modificación de red debe incluir un mecanismo de reversión automática.
  • Implementación:
    • Usar scripts con temporizador ("Dead Man's Switch").
    • Flujo:
      1. Aplicar cambios temporalmente.
      2. Esperar confirmación explícita del usuario (ej: presionar una tecla) durante un tiempo prudencial (5 minutos).
      3. Si no hay confirmación: Revertir cambios inmediatamente y restaurar estado anterior.
      4. Si hay confirmación: Hacer cambios persistentes.

7. Referencia de Iconografía

Para optimizar el escaneo visual de las bitácoras, se implementa una estricta separación de responsabilidades visuales:

1. Icono de Estado (Columna Tema)

Icono Significado Descripción
✅ Completado Tarea general finalizada exitosamente.
⏳ En Proceso Tarea en ejecución o pendiente de cierre.
⚠️ Fallo / Alerta Tarea fallida, cancelada o riesgo detectado.
📍 Definido Pendiente en la cola de planificación (Control de Gestión).
➡️ Migrado Tarea transferida a la bitácora del día siguiente (Rollover).

2. Iconos Semánticos (Prefijos y Viñetas de Hitos)

Icono Orientación Ejemplos de Uso
🟢 Operativo Servicio funcionando, confirmación de red, OK.
🔧 Configuración Mantenimiento, ajuste de parámetros, cambios de código.
🧪 Prueba Validación técnica, ensayos, simulaciones, logs.
🐛 Bug / Fix Errores de software, excepciones, correcciones.
🧹 Limpieza Refactorización, purga, reubicación de archivos.
💾 Datos Backups, volcados, sincronización de discos, almacenamiento.
🚀 Despliegue Lanzamiento masivo, ejecución grande, puesta en marcha.
👁️ Análisis Revisión humana, planificación, auditoría, brainstorming.
🧠 Estructura Conceptualización de arquitectura, metodologías, ideas críticas.
📝 Documentación Actualización del ADN, manuales, reportes, logs manuales.

8. Resguardo del Repositorio (Safeguard)

  • Objetivo: Asegurar la integridad y el historial de cambios del proyecto.
  • Directiva:
    • Frecuencia: Al finalizar una tarea significativa o conjunto de tareas relacionadas (hito).
    • Alcance: Todo cambio en adn/, servicios/config, scripts/ y documentación docs/.
    • Formato Mensaje: [Categoría] Descripción breve del cambio.

9. Evolución Progresiva (Mejora Continua)

  • Principio: El ADN no es estático; evoluciona a partir de los descubrimientos y buenas prácticas (emergentes) surgidas durante la operación diaria.
  • Flujo de Vida de una Mejora:
    1. Incubación (Prueba de Concepto): Una técnica experimental (ej. notas ocultas HTML para instanciar a la IA, rediseños de interfaces) se prueba bajo fuego en la trinchera (bitácoras diarias, scripts, reportes).
    2. Identificación: Se reconoce el valor sistémico y repetible de la técnica.
    3. Formalización: 4. UNIFICACIÓN: Una sola fila por Nodo en Resumen. 5. ESTADO ACTIVO: Tareas iniciadas sin finalizar van a 'En Proceso'. 6. IDENTIFICADORES: Usar el correlativo exacto del Tema (ej. [✅ - 09:13 - **dtic-BKPs C4**](#...)). 7. ARMONÍA: Consultar y seguir estrictamente las premisas del ADN (adn/02_protocolo.md)., adn/01_ontologia.md, etc.).
    4. Propagación: A partir de su formalización, la regla es de cumplimiento obligatorio para el trabajo futuro y, donde sea viable, se refactoriza el material previo para mantener la Consistencia (ver Sección 3).
  • Ejemplos Fundacionales:
    1. Estructura Dinámica: Las Premisas de Trabajo (IA) en el footer de las bitácoras nacieron como un experimento y evolucionaron orgánicamente hasta convertirse en un estándar estructural oficial (Sección 4.3).
    2. Migración Tecnológica (Bash → Ruby): El salto de scripts procedimentales en Bash hacia aplicaciones estructuradas en Ruby (dtic-BKPs). La operación real demostró que Bash resultaba frágil e inescalable para secuencias complejas. Ruby fue probado, identificado como superior por su manejo de excepciones y adaptabilidad estructural, formalizado en la reescritura de las herramientas, y propagado como el nuevo estándar de facto para construir utilidades dentro del repositorio.