system-audit

# System Audit — Auditoría Sistemática de Repositorios ## Resumen Procedimiento para auditar un repositorio o sistema de software completo: explorar la estructura, leer archivos clave, identificar fortalezas y debilidades, y proponer mejoras priorizadas. ## Cuándo usar - Usuario pide "auditoría", "review", "qué te parece", "qué mejorarías" de un repositorio o sistema - Evaluación de calidad antes de integrar un sistema nuevo - Revisión de un proyecto propio para detectar deuda técnica - Análisis de un framework o patrón encontrado en otro repo ## Flujo de Auditoría (5 pasos) ### Paso 1: Exploración de estructura ```bash # Árbol de archivos find . -maxdepth 2 -type f -o -type d | sort # Conteo de archivos find . -name "*.md" | wc -l # Log reciente git log --oneline -20 # Remote y branch git remote -v git branch -a ``` **Objetivo:** Entender la escala del proyecto, su historia reciente, y su superficie de código. ### Paso 2: Lectura de archivos clave (prioridad) Leer SIEMPRE estos archivos en orden: 1. **README** → Qué es el proyecto, cómo funciona, badges, estructura 2. **Archivo de entrada principal** (`AGENTS.md`, `README.md`, `index.html`, `main.py`, etc.) 3. **Configuración del sistema** (`config.yaml`, `_system-config.md`, `.env.example`) 4. **Documentación de arquitectura** (`ARCHITECTURE.md`, `docs/`) 5. **Workflow/CI** (`.github/workflows/`) 6. **Índices de conocimiento** (skills index, learnings index, clusters) 7. **Agentes/roles principales** (los que definen el comportamiento central) 8. **Plantillas** (templates que otros siguen) 9. **Estado actual** (session state, TODOs pendientes, tareas sin cerrar) ### Paso 3: Análisis de fortalezas Evaluar cada dimensión con criterio (MÍNIMO 8 dimensiones): | Dimensión | Qué buscar | |-----------|-----------| | **Arquitectura** | Separación de responsabilidades, patrones de diseño, capas | | **Memoria/conocimiento** | Cómo se almacena, filtra, recupera y deprecia el conocimiento | | **Orquestación** | Cómo se coordinan los componentes, flujos adaptativos | | **Calidad** | Revisión, criticado, validación, tests | | **Documentación** | README, arquitectura, templates, contribución | | **Portabilidad** | Rutas absolutas, dependencias de SO, configuración portable | | **UX/Comunicación** | Checkpoints, formatos de output, protocolos de delegación | | **Auto-mejora** | Aprendizaje acumulado, reaprendizaje, métricas | | **Tokens y costes** | Tracking de tokens, costes por sesión, optimización de contexto | | **Seguridad** | Secrets en repo, .gitignore correcto, credenciales hardcodeadas | | **Deploy/CI/CD** | Workflows funcionales, branches limpios, CI configurado | | **Integración móvil** | Telegram, accesibilidad desde móvil, canales de comunicación | **Regla:** Nunca evaluar menos de 8 dimensiones. Las dimensiones de tokens/costes, seguridad y deploy son OBLIGATORIAS en auditorías de sistemas multi-agente. ### Paso 4: Detección de problemas (categorías) Clasificar cada problema encontrado en una de estas categorías: | Categoría | Severidad | Ejemplos | |-----------|-----------|----------| | **🔴 Crítico** | Rompe el sistema o la portabilidad | Rutas absolutas hardcodeadas, estado corrupto, datos perdidos | | **🟡 Importante** | Limita la utilidad o escalabilidad | Sin métricas, mecanismo de auto-mejora sin usar, criterios subjetivos | | **🟢 Menor** | Mejora la calidad pero no bloquea | Branch naming, falta de CHANGELOG, CSS duplicado | ### Paso 5: Propuestas de mejora priorizadas Para cada problema, proponer una mejora concreta: - **Prioridad Alta** → Afecta portabilidad, funcionalidad o escalabilidad - **Prioridad Media** → Mejora la utilidad, mantenibilidad o coherencia - **Prioridad Baja** → Buenas prácticas, consistencia, documentación ## Patrones comunes que debes detectar ### Patrones de arquitectura bien diseñados - Dos capas (documental + ejecutable) sin duplicación - Índice inteligente con carga bajo demanda - Flujo adaptativo basado en complejidad - Agente de mantenimiento autónomo (bibliotecario/archiver) - Protocolos de comunicación estructurados ### Patrones de arquitectura problemáticos - Rutas absolutas hardcodeadas en config - Mecanismos de auto-mejora sin datos que los alimenten - Criterios subjetivos donde deberían ser objetivos - Estado de sesión sin limpieza (tareas "pendientes" que nunca se archivan) - CSS/estilos duplicados entre componentes - Verificador de instalación que solo funciona en un SO ### Patrones de memoria/conocimiento - Índice con señales de relevancia + decay (bueno) - Learnings individuales cargados siempre (malo — gasta tokens) - Skills sin "ciclo de reaprendizaje" cuando el mecanismo existe - Clusters dinámicos vs. estáticos ### Patrones de criticado — activación objetiva - **Señal de alerta:** El Critic se activa por "dudas" subjetivas del orchestrator - **Patrón correcto:** 6 criterios objetivos: complejidad ≥4, ≥3 reintentos, ≥3 archivos, impacto alto, reviewer emite WARNINGs, solicitud humana explícita - **Señal de éxito:** El orchestrator evalúa los criterios automáticamente sin preguntar ## Formato de output Presentar la auditoría en este formato: ``` # 🔍 Auditoría Completa — [Nombre del Sistema] ## 📊 Panorama General | Dimensión | Estado | |-----------|--------| | ... | ... | ## ✅ Lo que está MUY BIEN ### 1. [Nombre del aspecto positivo] [Explicación de POR QUÉ es bueno, no solo QUÉ es bueno] ## ⚠️ Problemas detectados ### 🔴 Críticos [Problema] → [Por qué es crítico] ### 🟡 Importantes [Problema] → [Por qué es importante] ### 🟢 Menores [Problema] → [Por qué es menor] ## 💡 Mejoras que propondría ### Prioridad Alta [A] [Mejora] → [Impacto esperado] ### Prioridad Media [B] [Mejora] → [Impacto esperado] ### Prioridad Baja [C] [Mejora] → [Impacto esperado] ## 📈 Veredicto global **Puntuación: X/10** [Resumen de 2-3 líneas con tu opinión honesta sobre el sistema] ``` ## Post-Audit Execution Pipeline Cuando el usuario autoriza ejecutar las mejoras propuestas en la auditoría: ### Paso 1: Priorizar por severidad | Prioridad | Categoría | Acción | |-----------|-----------|--------| | **P0** | 🔴 Crítico | Ejecutar inmediatamente (rompe funcionalidad) | | **P1** | 🟡 Importante | Ejecutar en orden de impacto | | **P2** | 🟢 Menor | Ejecutar al final o batch | ### Paso 2: Plan de cambios Antes de ejecutar, presentar plan concreto: ```python # Para cada problema P0: - Archivo: path/al/archivo.xyz - Cambio: descripción exacta del cambio - Líneas: ~20 afectadas - Riesgo: bajo/medio/alto # Para P1-P2, agrupar por dominio (docs, infra, código) ``` **Regla:** NO ejecutar sin presentar plan y obtener ✅ del usuario en cambios >3 archivos. ### Paso 3: Ejecución - **P0 individuales** → directo (terminator, patch) - **P0 paralelos independientes** → `delegate_task` en paralelo - **P1-P2 relacionados** → agrupar en un `delegate_task` con todas las instrucciones - **Documentación** → Mastermind directo (no requiere delegación) - **CI/Deploy** → revisar primero, luego ejecutar ### Paso 4: Verificación Por cada grupo de cambios ejecutado: 1. `git diff --stat` para confirmar archivos tocados 2. Esanear referencias residuales con `search_files` 3. `git commit` con mensaje en castellano y descriptivo 4. `git push` ### Paso 5: Medir delta Al final de la ejecución: ```diff - Pre-auditoría: 5.6/10 + Post-ejecución: ~7.5/10 + Delta: +1.9 puntos ``` Incluir el delta en el resumen final para que el usuario vea el progreso tangible. ### Alternativa: Pipeline de Crons Secuenciales Cuando el usuario no puede estar presente para supervisar la ejecución en vivo (o las mejoras son muchas y deben ejecutarse una por una): 1. **Crear crons `once` escalonados** (15-20 min de separación), cada uno autocontenido 2. **Cada cron hace UNA mejora concreta**: lee archivos → ejecuta cambio → verifica → commit → resumen 3. **Todos con `deliver: origin`** para que el usuario vea el progreso en tiempo real 4. **Último cron = REVISIÓN FINAL**: verifica checklist completo, y si algo falla → crea cron de reparación 5. **Independientes**: si uno falla, el siguiente igual funciona (no hay dependencias entre ellos) 6. **Idempotentes**: re-ejecutar uno no rompe nada **Formato del prompt de cada cron:** ``` Eres Mastermind. TAREA: [descripción concreta] PASOS: 1. [leer/verificar] 2. [ejecutar cambio] 3. [verificar cambio] 4. [commit + push] RESUMEN: [qué cambió antes→después] ``` **Patrón probado:** 14 crons secuenciales para ejecutar mejoras de auditoría, divididos en dos fases: - **Fase 1 (8 crons):** Infraestructura y limpieza — README real, Mastermind disclaimer, ChromaDB auto-start, ChromaDB re-index, SOUL.md integration, skill dedup, skill priority consolidation, crons pausados eliminados - **Fase 2 (6 crons):** Inteligencia — memoria decay (Ebbinghaus), knowledge graph, skill lifecycle, delegation flows, dashboard HTML, revisión final - **Cada cron es autocontenido** (lee → ejecuta → verifica → commit → resumen) e **idempotente** (re-ejecutar no rompe nada) - **El cron de revisión final** verifica checklist completo y crea un **cron de mantenimiento semanal** que re-ejecuta todo los domingos - **Fase 2 depende de Fase 1** — los crons de inteligencia usan scripts/paths creados en Fase 1. Separar en fases evita que un fallo en infra destruya features de inteligencia ## Post-Migration Cleanup Execution Cuando una migración de plataforma/paradigma ya se completó (v3.1→v4.0, de Obsidian→GitHub, etc.), a menudo quedan **referencias residuales** en los archivos activos. El ejecutable de limpieza sigue este flujo: ### Paso 1: Escaneo sistemático de referencias legacy Usar `search_files` con los nombres de la plataforma antigua para encontrar TODAS las referencias en archivos activos (excluyendo `legacy/` y `.git/`): ```python patterns = ['obsidian', 'opencode', 'ebbinghaus', 'wikilink', '[[', 'slash command'] for root, dirs, files in os.walk(base): # excluir .git, legacy/, learning-platform/ for fname in files: if fname.endswith(('.md', '.json', '.html', '.yml', '.sh', '.bat', '.js')): # buscar cada patrón, reportar línea exacta ``` ### Paso 2: Clasificar cada referencia | Tipo | Acción | Ejemplo | |------|--------|---------| | **Contexto de migración** (CHANGELOG, tablas comparativas) | ✅ Mantener | "v3.1 usaba OpenCode + Obsidian" | | **Instrucciones activas** (CONTRIBUTING, guías de inicio) | 🔄 Reescribir | "Abrir como vault de Obsidian" | | **Landing page desactualizada** | 🔄 Reescribir | index.html con 11 agentes, Ebbinghaus | | **Scripts de verificación obsoletos** | 🔄 Actualizar o 🗑️ eliminar | verify-system.bat que chequea .opencode/ | | **Documentación en otro idioma desactualizada** | 🔄 Simplificar o 🗑️ eliminar | README_EN.md que v3.1 | | **READMEs y docs que comparan versiones** | ✅ Mantener | Las comparativas dan contexto | ### Paso 3: Ejecutar cambios por archivo Para cada archivo que necesita cambios: - **Landing page**: Reescribir entera (cambia el mensaje, el branding, los KPIs) - **CONTRIBUTING**: Reescribir entero (las instrucciones de instalación cambian completamente) - **CHANGELOG**: Traducir/actualizar manteniendo el historial - **Scripts de sistema**: Actualizar estructura de verificación al nuevo layout - **Workflows CI**: Actualizar excludes de paths que ya no existen ### Paso 4: Verificación final Re-escanear para confirmar que no quedan referencias activas: ```bash grep -rl "obsidian\|opencode\|ebbinghaus" --include="*.md" --include="*.html" . | grep -v legacy/ | grep -v .git/ ``` Luego: `git add -A && git commit` con mensaje descriptivo + push. Ver `references/post-migration-cleanup.md` para el caso real de limpieza del Mastermind v3.1→v4.0. ## Adjunto: Auditoría de apps Node.js multi-usuario (Express + SQLite) Cuando el proyecto auditado es una **aplicación web Node.js con Express, SQLite (sql.js) y autenticación multiusuario**, añadir estas dimensiones específicas al flujo de 5 pasos: ### Dimensiones adicionales obligatorias | Dimensión | Qué buscar | Patrón problema | Referencia | |-----------|-----------|-----------------|------------| | **Helpers SQL** | ¿`sql_run`, `sql_all`, `sql_get` existen? ¿Se usan correctamente? | `sql_run()` para SELECT → datos perdidos silenciosamente | Patrón 1 | | **Aislamiento multi-tenant** | ¿Los datos de cada usuario están aislados por `usuario_id`? | `getMeta('nombre')` global en vez de `usuarios.nombre` | Patrón 2 | | **Auth** | Token en header vs cookie. ¿Limpieza de sesiones expiradas? | Token en URL (logs), sin cleanup periódico | Patrón 3 | | **Onboarding** | ¿Formulario fijo o conversacional? ¿Se adapta al usuario? | Pasos fijos sin IA, sin personalidad de coach | Patrón 4 | | **Persistencia de chat** | ¿Mensajes de IA en servidor o solo localStorage? | Chat perdido al cambiar navegador/dispositivo | Patrón 5 | ### Cómo leer la referencia El archivo `references/nodejs-multiuser-audit-patterns.md` contiene 5 patrones detallados con: - Síntoma (cómo lo detecta un usuario) - Causa (qué código lo produce) - Detección automática (comandos grep/curl) - Verificación funcional (cómo confirmar el bug) - Lección (cómo prevenirlo en el futuro) ### Checklist rápido para auditoría Node.js multi-usuario ```bash # 1. Verificar helpers SQL grep -n "function sql_run\|function sql_all\|function sql_get" server.js # 2. Buscar sql_run usado para SELECT (antipattern) grep -n "sql_run.*SELECT" server.js # 3. Buscar getMeta() en funciones perfilUsuario grep -n "getMeta" server.js | grep -i "nombre\|perfil\|user" # 4. Verificar auth: limpieza de sesiones grep -n "DELETE FROM sesiones" server.js # 5. Verificar si chat tiene persistencia en servidor grep -n "chat\|mensaje\|conversacion" server.js # 6. Verificar aislamiento multi-tenant en todas las queries grep -n "usuario_id" server.js | head -20 # 7. Verificar onboarding grep -n "onboarding\|onboard" server.js ``` ## Audit de Skills del Ecosistema Cuando el usuario pide auditar el ecosistema de skills (detectar duplicados, project-readmes, CLI wrappers, skills sin tags), usar el patrón `skill-audit-pattern` como subsección: ### Pasos 1. **Inventario**: contar skills, verificar frontmatter (version, description, tags) 2. **Detectar project-readmes**: skills con rutas absolutas de proyecto (>5 rutas = project-readme)