Skip to content

PULL_REQUEST_INTERCEPTION.es.md

Latest commit

 

History

History
83 lines (58 loc) · 5.41 KB

PULL_REQUEST_INTERCEPTION.es.md

File metadata and controls

83 lines (58 loc) · 5.41 KB
Raw

Flujo de Intercepción de Pull Requests

Navegación Bilingüe: English · Español (este documento)

En el ecosistema Evolith, las solicitudes de extracción (pull requests) de SCM no son meros puntos de control de revisión de código delegados a revisores humanos propensos a errores. Son puertas gobernadas interceptadas y verificadas programáticamente por agentes autónomos antes de que el código sea fusionado. Este documento especifica el flujo arquitectónico y las reglas de negocio que gobiernan la intercepción de pull requests en Evolith Tracker.

1. Integración Agnóstica de Repositorio (ACL Inbound)

Evolith Tracker mantiene cero conocimiento directo de las APIs específicas de los proveedores de SCM o de los ejecutores de pipelines (como GitHub Actions, GitLab CI o Bitbucket Pipelines). En su lugar:

  • Abstracción de la ACL Inbound: Las plataformas de SCM interactúan con el Tracker a través de una Capa Anti-Corrupción (ACL) de repositorio dedicada.
  • Mapeo de Webhooks: Cuando se crea, actualiza o confirma (commit) una solicitud de extracción, el SCM dispara eventos genéricos enviados a la ACL Inbound.
  • Ingesta Canónica: La ACL traduce el payload del SCM específico del proveedor (commits, archivos modificados, metadatos del autor) al objeto de valor canónico CodeProposal de Tracker, protegiendo el modelo de dominio interno de la contaminación de esquemas externos.

2. Auditoría Arquitectónica Agéntica

Una vez que se ingiere un CodeProposal:

  • Disparador de Validación de Drift: El núcleo de Tracker despacha la propuesta al Agente de Arquitectura para su auditoría.
  • Cumplimiento del Corpus: El agente valida los archivos de la propuesta contra las reglas y planos arquitectónicos cacheados del Progressive Architecture Reference Corpus (Evolith Core).
  • Verificaciones Automatizadas: El agente verifica los límites de los paquetes, la conformidad de las interfaces, las restricciones de dirección de las dependencias y asegura que no existan violaciones de ADR no documentadas en los cambios de código.

3. Ejecución: Bloqueo de Architecture Drift

Evolith Tracker trata las especificaciones arquitectónicas como restricciones obligatorias en tiempo de compilación:

  • Bloqueo Estricto: Si el Agente de Arquitectura detecta violaciones de diseño o Architecture Drift (BR-004), el estado de la gate se marca como BLOCKED.
  • Callback de la ACL Outbound: La ACL Outbound traduce este bloqueo en una acción específica del proveedor:
    • En GitHub, establece el estado de la verificación como FAILED y bloquea el botón de fusión (merge).
    • En GitLab, bloquea la solicitud de fusión y envía una notificación de rechazo.
  • Comentarios del Agente: El Agente de Arquitectura publica automáticamente un comentario detallado de revisión de código en las líneas del PR donde se detectaron las desviaciones, detallando las violaciones técnicas y las remediaciones requeridas.

4. Anulaciones de Excepciones Manuales (Loop Engineer)

Evolith opera bajo el principio de que la IA automatiza la verificación pero los humanos conservan el control final de la gobernanza.

  • Restricción de Anulación: Las verificaciones de estado a nivel de SCM no pueden ser omitidas por desarrolladores estándar, Tech Leads ni administradores del SCM.
  • Autoridad del Loop Engineer: El Loop Engineer (operando como el rol humano autoritativo en este contexto) es la única autoridad humana capaz de anular una verificación de PR bloqueada por deriva.
  • Solicitud de Excepción en Tracker: Para aprobar un PR bloqueado, el desarrollador debe registrar una ExceptionRequest formal dentro del Tracker. El Loop Engineer revisa la justificación de la excepción contra el Grafo de Evidencias. Si se aprueba, el núcleo de Tracker comanda a la ACL Outbound forzar la aprobación de la verificación del SCM, capturando la firma de aprobación en la pista de auditoría inmutable.

5. Diagrama de Secuencia de Intercepción de Extremo a Extremo

El siguiente diagrama ilustra el flujo de intercepción y verificación de solicitudes de extracción:

sequenceDiagram
    autonumber
    participant SCM as "GitHub / GitLab (SCM)"
    participant ACL as "Inbound/Outbound ACL"
    participant TRK as Evolith Tracker Core
    participant AGT as Architecture Agent
    participant ENG as "Loop Engineer (Rol Humano)"

    SCM->>ACL: Pull Request Creado / Actualizado (Evento Webhook)
    ACL->>TRK: Ingesta de evento CodeProposal normalizado
    TRK->>AGT: Disparar Auditoría de Arquitectura
    AGT->>AGT: Validar modificaciones de código contra reglas de Evolith Core
    
    alt Código es Cumplidor
        AGT-->>TRK: Veredicto de Auditoría: COMPLIANT
        TRK->>ACL: Aprobar verificación de estado
        ACL->>SCM: Cambiar estado del check de PR a SUCCESS (Permitir merge)
    else Código contiene Drift (Deriva)
        AGT-->>TRK: Veredicto de Auditoría: NON-COMPLIANT
        TRK->>ACL: Rechazar verificación de estado
        ACL->>SCM: Cambiar estado del check de PR a FAILED (Bloquear merge) y Publicar feedback
        
        Note over SCM,ENG: Flujo de Anulación Manual
        ENG->>TRK: Autorizar ExceptionRequest (con justificación)
        TRK->>ACL: Forzar aprobación de verificación de estado
        ACL->>SCM: Cambiar estado del check de PR a SUCCESS (Anular bloqueo)
    end
Loading