Skip to content

PULL_REQUEST_INTERCEPTION.md

Latest commit

 

History

History
83 lines (58 loc) · 4.62 KB

PULL_REQUEST_INTERCEPTION.md

File metadata and controls

83 lines (58 loc) · 4.62 KB

Pull Request Interception Flow

Bilingual Navigation: English (this document) · Versión en Español

In the Evolith ecosystem, SCM pull requests are not merely code review checkpoints left to error-prone human reviewers. They are governed gateways programmatically intercepted and verified by autonomous agents before code is merged. This document specifies the architectural flow and rulesets governing SCM pull request interception within Evolith Tracker.

1. Agnostic Repository Integration (Inbound ACL)

Evolith Tracker maintains zero direct awareness of specific SCM vendor APIs or pipeline runners (such as GitHub Actions, GitLab CI, or Bitbucket Pipelines). Instead:

  • Inbound ACL Abstraction: SCM platforms interact with the Tracker through a dedicated repository Anti-Corruption Layer (ACL).
  • Webhook Mapping: When a pull request is created, updated, or committed, the SCM triggers generic events sent to the Inbound ACL.
  • Canonical Ingestion: The ACL translates the vendor-specific SCM payload (commits, files modified, author metadata) into the Tracker's canonical CodeProposal value object, protecting the inner domain model from vendor-specific schema contamination.

2. Agentic Architecture Audit

Once a CodeProposal is ingested:

  • Drift Validation Trigger: The Tracker core dispatches the proposal to the Architecture Agent for auditing.
  • Corpus Compliance: The agent validates the proposal's files against the rulesets and blueprints cached from the Progressive Architecture Reference Corpus (Evolith Core).
  • Automated Checks: The agent verifies package boundaries, interface conformance, dependency direction constraints, and ensures no undocumented ADR violations exist in the code changes.

3. Enforcement: Blocking Architecture Drift

Evolith Tracker treats architectural specs as non-negotiable compile-time constraints:

  • Strict Blocking: If the Architecture Agent detects any design violations or Architecture Drift (BR-004), the gate status is marked as BLOCKED.
  • Outbound ACL Callback: The Outbound ACL translates this block into a vendor-specific action:
    • In GitHub, it sets the status check to FAILED and blocks the merge button.
    • In GitLab, it locks the merge request and posts a rejection notification.
  • Agent Feedback: The Architecture Agent automatically posts a detailed code review comment on the PR lines where the deviations were detected, outlining the technical violations and required remediations.

4. Manual Exception Overrides (Loop Engineer)

Evolith operates under the principle that AI automates verification but humans retain final governance control.

  • Override Restriction: SCM-level status checks cannot be bypassed by standard developers, Tech Leads, or SCM administrators.
  • Loop Engineer Authority: The Loop Engineer (operating as the authoritative human role in this context) is the only human authority capable of overriding a drift-blocked PR check.
  • Tracker Exception Request: To approve a blocked PR, the developer must raise a formal ExceptionRequest inside the Tracker. The Loop Engineer reviews the exception justification against the Evidence Graph. If approved, the Tracker core commands the Outbound ACL to force-approve the SCM status check, capturing the approval signature in the immutable audit trail.

5. End-to-End Interception Sequence Diagram

The following diagram illustrates the pull request interception and verification flow:

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 (Human Role)"

    SCM->>ACL: Pull Request Created / Updated (Webhook Event)
    ACL->>TRK: Ingest normalized CodeProposal event
    TRK->>AGT: Trigger Architecture Audit
    AGT->>AGT: Match code modifications with Evolith Core rulesets
    
    alt Code is Compliant
        AGT-->>TRK: Audit Verdict: COMPLIANT
        TRK->>ACL: Approve status check
        ACL->>SCM: Set PR check status to SUCCESS (Enable merge)
    else Code contains Drift
        AGT-->>TRK: Audit Verdict: NON-COMPLIANT
        TRK->>ACL: Reject status check
        ACL->>SCM: Set PR check status to FAILED (Block merge) & Post review feedback comment
        
        Note over SCM,ENG: Manual Override Flow
        ENG->>TRK: Authorize ExceptionRequest (with justification)
        TRK->>ACL: Force-approve status check
        ACL->>SCM: Set PR check status to SUCCESS (Override block)
    end
Loading