From aedc9670b9583d176f035af662874b6a97173028 Mon Sep 17 00:00:00 2001 From: David Nestor Monroy Valero <169318663+jcg-admin@users.noreply.github.com> Date: Mon, 24 Nov 2025 09:19:43 -0600 Subject: [PATCH] docs(gobernanza): document restriction inventory --- .../reglas_restricciones_detalle.md | 40 +++++++++++++++++++ ...resumen_artefactos_reglas_restricciones.md | 22 ++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/gobernanza/reglas_restricciones_detalle.md create mode 100644 docs/gobernanza/resumen_artefactos_reglas_restricciones.md diff --git a/docs/gobernanza/reglas_restricciones_detalle.md b/docs/gobernanza/reglas_restricciones_detalle.md new file mode 100644 index 00000000..24e337db --- /dev/null +++ b/docs/gobernanza/reglas_restricciones_detalle.md @@ -0,0 +1,40 @@ +# Reglas y restricciones: detalle operativo + +## Objetivo + +Proveer un punto único donde se describan las restricciones críticas vigentes, su nivel de severidad y cómo se hacen cumplir en el proyecto. Esta vista complementa el inventario de artefactos documentado en `resumen_artefactos_reglas_restricciones.md`. + +## Clasificación y criticidad + +- **Críticas (P0)**: bloquean merges y despliegues si se incumplen. Incluyen prohibiciones tecnológicas y salvaguardas operativas. +- **Mayores (P1)**: deben resolverse en el mismo sprint, afectan calidad o seguridad. +- **Informativas (P2)**: guías que no bloquean, pero se auditan en QA. + +## Restricción crítica: Prohibición de envío de correos electrónicos reales + +- **Descripción**: El envío de correos electrónicos reales está prohibido; solo se permite mensajería interna o mecanismos simulados. +- **Dónde se controla**: + - `scripts/validate_critical_restrictions.sh` detecta imports/uso de librerías de email y falla si se encuentran. + - `scripts/ci/gate-restrictions.sh` ejecuta los chequeos en CI y bloquea merges. + - `docs/gobernanza/guias/scripts/validate_critical_restrictions.md` documenta los patrones prohibidos y las alternativas (`InternalMessage`). +- **Aplicación esperada**: + - Configuraciones de aplicaciones deben deshabilitar backends SMTP reales y usar mensajería interna. + - Los tests deben mockear cualquier interacción con correo externo. + - Las plantillas y checklists deben registrar evidencia de que no se envían correos reales en ningún entorno. + +## Checklist de cobertura rápida + +1. **Inventario**: confirmar que `resumen_artefactos_reglas_restricciones.md` refleja los artefactos actuales y su fecha de revisión. +2. **Severidad**: marcar cada restricción como crítica, mayor o informativa. +3. **Trazabilidad**: para cada restricción crítica, enlazar los artefactos donde se define y los scripts que la validan. +4. **Evidencia**: adjuntar logs de `scripts/validate_critical_restrictions.sh` y resultados de `scripts/ci/gate-restrictions.sh` en las carpetas de QA. +5. **Operacionalización**: documentar cómo se aplica la restricción en configuración (ej. deshabilitar SMTP) y en pruebas (mocks de email). +6. **Plantillas/procesos**: asegurar que las plantillas de reglas de negocio y checklists de QA exigen evidencias actualizadas. +7. **Excepciones**: registrar cualquier excepción aprobada con su ADR o issue de referencia. +8. **Gobernanza**: fechar este documento y asignar responsable de mantener la trazabilidad. + +## Registro y responsables + +- **Última actualización**: completar con la fecha de la próxima revisión. +- **Responsable**: equipo de arquitectura y QA de gobernanza. +- **Próxima acción**: al agregar nuevas restricciones críticas, actualizar este documento y el resumen para mantener la cobertura. diff --git a/docs/gobernanza/resumen_artefactos_reglas_restricciones.md b/docs/gobernanza/resumen_artefactos_reglas_restricciones.md new file mode 100644 index 00000000..370c3161 --- /dev/null +++ b/docs/gobernanza/resumen_artefactos_reglas_restricciones.md @@ -0,0 +1,22 @@ +# Resumen de artefactos de reglas y restricciones + +## Propósito + +Este resumen consolida los artefactos donde se documentan, validan y auditan las restricciones del proyecto. Sirve como punto de entrada para localizar fuentes de verdad antes de aprobar nuevas reglas o revisar su cumplimiento. + +## Rutas principales + +- **Documentación base**: `docs/backend/requisitos/restricciones_y_lineamientos.md` y `docs/frontend/requisitos/reglas_negocio/restricciones.md` definen las restricciones maestras por dominio. +- **Checklists y plantillas**: `docs/gobernanza/qa/checklist_auditoria_restricciones.md` y `docs/gobernanza/templates/RN-restriccion-template.md` estandarizan cómo se evidencian las validaciones. +- **Guías de guiones**: `docs/gobernanza/guias/scripts/validate_critical_restrictions.md` describe el alcance del script crítico de validación. +- **Automatizaciones CI**: `scripts/ci/gate-restrictions.sh` bloquea merges si fallan validaciones de restricciones. +- **Validadores centrales**: `scripts/validate_critical_restrictions.sh` ejecuta chequeos sobre uso de email, Sentry, sesiones y otros riesgos críticos. +- **Agentes de código**: `scripts/coding/ai/agents/validation/restrictions_gate.py` replica las verificaciones para revisiones asistidas por IA. +- **QA de infraestructura**: `docs/infraestructura/qa/testing/comandos_validacion.md` registra cómo invocar los comandos de control en ambientes. + +## Cómo usar este resumen + +1. Revisar la documentación base antes de introducir nuevas restricciones o excepciones. +2. Ejecutar los scripts de validación (`scripts/validate_critical_restrictions.sh` y `scripts/ci/gate-restrictions.sh`) antes de abrir PRs. +3. Registrar la evidencia en las plantillas de QA y checklists de gobernanza. +4. Sincronizar cualquier cambio en restricciones críticas con los agentes/validadores en `scripts/coding/ai/`.