AI-LAB-PHASE-CLOSURE-PROTOCOL-01

La documentación forma parte del sistema. Una fase no está cerrada hasta que la documentación asociada está actualizada, indexada y verificable.

Este protocolo aplica a toda fase que:

• Introduzca nueva funcionalidad, componente o servicio
• Modifique arquitectura, rutas o dependencias
• Cambie responsabilidades entre dominios
• Añada o modifique nodos de infraestructura
• Modifique procedimientos operativos
• Cambie políticas de governance o seguridad
• Modifique contratos o APIs expuestas
• Introduzca nuevos modelos o cambie el modelo set activo
• Modifique el stack de observabilidad

• Fases exclusivamente READ-ONLY (auditorías, investigaciones)
• Fases de documentación pura sin cambios operacionales
• Correcciones de typos o erratas sin impacto semántico

En estos casos, el cierre puede ser PARTIAL (ver criterios abajo).

Antes de cerrar una fase, responder:

Si ninguna respuesta es “Si”, el cierre puede ser PARTIAL (solo actualizar fases list).

Ejecutar en orden:

1. Documentación canónica: crear o modificar documentos en apps/ialab-docs/src/content/docs/
2. AGENTS.md: actualizar lista de fases, próxima fase, roadmap y reglas si aplica
3. OPENCODE.md: actualizar si cambia el perfilado o las instrucciones del agente
4. anythingllm-core/: actualizar si cambia infraestructura o documentación canónica

Si se modificó apps/ialab-docs/:

cd /opt/ai-lab/apps/ialab-docs
npm run build

Criterio: build debe completar sin errores. Warnings de chunk size se permiten.

Si la fase tiene impacto documental:

1. Verificar qué documentos nuevos o modificados deben indexarse
2. Acceder al panel de AnythingLLM
3. Seleccionar el workspace AI-LAB
4. Ejecutar “Reindex” en el workspace
5. Esperar a que la indexación complete

Si no es posible reindexar (entorno no disponible, fase puramente documental en workspace SMB), el cierre puede ser PARTIAL documentando la razón.

Formular al menos 2 preguntas representativas sobre el contenido nuevo y verificar que AnythingLLM las responde correctamente usando la documentación indexada.

Ejemplos de preguntas según el cambio:

Criterio PASS: las respuestas son correctas y están basadas en la documentación indexada.

Cada fase cerrada debe incluir en su resumen (AGENTS.md, commit message, o documento de fase):

Documentación: [actualizada / no aplica]
Build Astro: [PASS / no aplica / FAIL]
AnythingLLM: [reindexado / no aplica / pendiente (razón)]
Validación: [PASS / no aplica / pendiente]
Estado cierre: [PASS / PARTIAL / FAIL]

Las fases de auditoría, investigación o diagnóstico sin cambios en el sistema no requieren reindexación AnythingLLM. El cierre puede ser PASS si:

• El informe de auditoría está documentado
• No hay documentación canónica nueva que indexar
• No hay cambios en AGENTS.md más allá de añadir la fase a la lista

Fases que solo crean o modifican documentación (sin cambios operacionales ni de infraestructura) requieren:

• Build Astro (si afecta a Astro)
• Reindexación AnythingLLM (si los documentos son canónicos)
• Validación de recuperación

Si una fase debe cerrarse rápido por emergencia operativa, se permite PARTIAL con documentación de la razón. La reindexación y validación deben completarse dentro de las siguientes 24h o en la siguiente fase programada.

El pipeline de publicación documental automatiza los pasos 3-5 de este protocolo:

• scripts/phase-closure/invoke-phase-closure.ps1 — orquestador que ejecuta public Astro, private Astro, AnythingLLM reindex y smoke queries
• scripts/phase-closure/publish-astro-public.ps1 — build, commit, push, wait Cloudflare, validate
• scripts/phase-closure/publish-astro-private.ps1 — SSH, pull, build, restart, validate
• scripts/anythingllm/reindex-workspace.ps1 — reindex AnythingLLM vía API

Ver document-publishing-automation.md para detalles de uso y configuración.