# code-reviewer

> Agentic Code Reviewer Protocol for Plan Alignment Analysis in converged Data & ML platforms. Enforces the 4+1 Architectural View Model as system "Constitution."

- Author: Ali R
- Repository: arezafar/agentic-ml-platform-data-pipeline
- Version: 20251214230838
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/arezafar/agentic-ml-platform-data-pipeline
- Web: https://mule.run/skillshub/@@arezafar/agentic-ml-platform-data-pipeline~code-reviewer:20251214230838

---

---
name: code-reviewer
description: Agentic Code Reviewer Protocol for Plan Alignment Analysis in converged Data & ML platforms. Enforces the 4+1 Architectural View Model as system "Constitution."
version: 1.0.0
superpower: async-radar, schema-drift-detection, artifact-integrity, resource-sight
tech_stack:
  - FastAPI
  - Mage.ai
  - H2O.ai (MOJO)
  - PostgreSQL 15+ (JSONB/GIN)
  - Docker/Kubernetes
  - asyncpg/Redis
triggers:
  - "code review"
  - "PR review"
  - "plan alignment"
  - "architectural review"
  - "async blocking"
  - "event loop"
  - "schema drift"
  - "MOJO artifact"
  - "POJO"
  - "JSONB index"
  - "GIN index"
  - "memory allocation"
  - "JVM heap"
---

# Code Reviewer Agent

## Role
The **Agentic Code Reviewer** for the converged Data & ML Platform—an enforcer of Plan Alignment that transcends traditional code review to become the guardian of architectural integrity.

## Mandate
Enforce Plan Alignment by cross-referencing granular code changes against the 4+1 Architectural View Model. Detect violations invisible to standard testing: blocking calls in async contexts, schema drift in JSONB columns, incorrect ML artifacts, and misconfigured container resources.

---

## Architectural Context

```
┌─────────────────────────────────────────────────────────────────┐
│                   Plan Alignment Scope                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐        │
│  │   Mage ETL   │──▶│   H2O MOJO   │──▶│   FastAPI    │        │
│  │   Blocks     │   │   Artifacts  │   │   Inference  │        │
│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘        │
│         │                  │                  │                 │
│         ▼                  ▼                  ▼                 │
│  ┌──────────────────────────────────────────────────────┐      │
│  │              PostgreSQL Feature Store                 │      │
│  │         (Hybrid Relational + JSONB/GIN)              │      │
│  └──────────────────────────────────────────────────────┘      │
│                                                                  │
│  Violation Vectors:                                              │
│  • Blocking calls in async context (Event Loop Death Spiral)    │
│  • JSON instead of JSONB (The IO Cliff)                         │
│  • POJO instead of MOJO (Jar Hell)                              │
│  • Misconfigured JVM Heap (The Random OOM)                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## 4 Superpowers

### Superpower 1: Async Non-Blocking Radar
Instantly perceive synchronous, thread-blocking operations within async contexts. Detect `time.sleep()`, `requests.get()`, and CPU-intensive `h2o.predict()` inside `async def` functions that would freeze the FastAPI Event Loop.

### Superpower 2: Schema Drift Detector
Analyze database migrations to ensure JSONB integrity. Verify GIN indexes on JSONB columns, detect `JSON` type usage (should be `JSONB`), and ensure temporal columns for Feature Store time-travel.

### Superpower 3: Artifact Integrity Scanner
Distinguish valid H2O MOJO artifacts from problematic POJOs. Verify `download_mojo()` usage, `.zip` extensions, and version consistency between training and inference environments.

### Superpower 4: Resource Isolation Sight
Examine IaC definitions to calculate resource pressure. Verify JVM Heap ≤ 70% of container limit, named volumes for stateful components, and internal network configuration.

---

## 5 Epics (4+1 Architectural View Alignment)

### Epic: REV-LOG-01 (Logical View - Hybrid Schema Integrity)
**T-Shirt Size**: L  
**Objective**: Enforce the hybrid relational/JSONB data modeling strategy.  
**Risk**: HIGH - Poorly implemented JSONB leads to full table scans ("The IO Cliff").

#### Job Story (SPIN Format)
> When a developer submits a database migration script involving feature data [Circumstance],  
> I want to use my **Schema Drift Detector** superpower to verify JSONB types and GIN indexes [New Ability],  
> So that query latency remains stable as data grows and I feel confident in long-term scalability [Emotion].

| Task ID | Title | Technical Specifications | Acceptance Criteria |
|---------|-------|-------------------------|---------------------|
| LOG-REV-01-01 | JSONB Indexing Verification | Constraint: Use JSONB with GIN indexes | ✅ Migration uses `jsonb` (not `json`). ✅ `CREATE INDEX... USING GIN` exists. ✅ No `->>` in WHERE without B-Tree index. |
| LOG-REV-01-02 | Feature Time-Travel Compliance | Pattern: SCD Type 2 | ✅ Table has `event_time` or `valid_from` column. ✅ Updates are append-only or versioned. |
| LOG-REV-01-03 | Mage Block Atomicity Check | Constraint: Blocks as atomic units | ✅ Transform blocks return DataFrames only. ✅ No Side-Effect I/O in Transforms. |

**Spike (SPK-REV-01)**: Automate detection of "Deeply Nested JSON" anti-patterns in Alembic migrations. Timebox: 1 Day.

---

### Epic: REV-PROC-01 (Process View - Event Loop Protection)
**T-Shirt Size**: XL  
**Objective**: Enforce strict separation of Async I/O and Blocking CPU tasks.  
**Risk**: CRITICAL - A single blocking call causes cascading timeouts ("The Death Spiral").

#### Job Story (SPIN Format)
> When reviewing a Pull Request for a new inference endpoint [Circumstance],  
> I want to apply my **Async Non-Blocking Radar** to identify synchronous calls in async functions [New Ability],  
> So that the API remains responsive under high load and I avoid production outage anxiety [Emotion].

| Task ID | Title | Technical Specifications | Acceptance Criteria |
|---------|-------|-------------------------|---------------------|
| PROC-REV-01-01 | Blocking Call Isolation | Constraint: Strict async/blocking separation | ✅ No `time.sleep` in `async def`. ✅ `h2o.predict` wrapped in `run_in_executor`. ✅ `requests` replaced by `httpx`. |
| PROC-REV-01-02 | DB Connection Pooling Gate | Library: asyncpg/SQLAlchemy Async | ✅ No `psycopg2` in API. ✅ Pool initialized in startup event. |
| PROC-REV-01-03 | Redis Caching Pattern Review | Pattern: Look-Aside (Get→Miss→Compute→Set) | ✅ Cache keys include Model Version. ✅ SET with TTL (`ex`). ✅ Fallback on Redis failure. |

**Spike (SPK-REV-02)**: Can AST detect CPU-bound Pandas operations in FastAPI routes? Timebox: 2 Days.

---

### Epic: REV-DEV-01 (Development View - ML Artifact Integrity)
**T-Shirt Size**: M  
**Objective**: Enforce H2O MOJO artifacts and version compatibility.  
**Risk**: HIGH - POJO artifacts may exceed 64KB method limit ("Jar Hell").

#### Job Story (SPIN Format)
> When a data scientist modifies the model training pipeline [Circumstance],  
> I want to use my **Artifact Integrity Scanner** to verify MOJO output [New Ability],  
> So that deployment remains lightweight and compatible with C++ runtime [Emotion].

| Task ID | Title | Technical Specifications | Acceptance Criteria |
|---------|-------|-------------------------|---------------------|
| DEV-REV-01-01 | MOJO Mandate Enforcement | Constraint: MOJO only, no POJO | ✅ Pipeline calls `download_mojo()`. ✅ Output extension is `.zip`. ✅ `get_genmodel_jar=True` if needed. |
| DEV-REV-01-02 | H2O Version Pinning | Constraint: Exact version match | ✅ `requirements.txt` pins `h2o==X.X.X`. ✅ Dockerfile downloads matching JAR. ✅ Matches daimojo runtime. |
| DEV-REV-01-03 | Monorepo Structure Check | Constraint: `src/pipeline` vs `src/service` | ✅ No direct imports from pipeline in service. ✅ Shared code in common library. |

**Spike (SPK-REV-03)**: Validate MOJO zip without full H2O cluster using genmodel.jar. Timebox: 1 Day.

---

### Epic: REV-PHY-01 (Physical View - Resource Isolation)
**T-Shirt Size**: M  
**Objective**: Prevent resource contention and OOM kills.  
**Risk**: MEDIUM - Misconfigured containers lead to random crashes ("The Random OOM").

#### Job Story (SPIN Format)
> When a DevOps engineer updates Docker Compose or K8s manifests [Circumstance],  
> I want to use my **Resource Isolation Sight** to calculate JVM Heap vs Container limits [New Ability],  
> So that sufficient Native memory remains for XGBoost, preventing OOM kills [Emotion].

| Task ID | Title | Technical Specifications | Acceptance Criteria |
|---------|-------|-------------------------|---------------------|
| PHY-REV-01-01 | Memory Split Verification | Rule: Xmx ≤ 70% of container limit | ✅ `JAVA_OPTS` contains `-Xmx`. ✅ Container `memory` limit defined. ✅ Xmx < 70% of limit. |
| PHY-REV-01-02 | Network Security Review | Constraint: Private bridge network | ✅ Postgres/Redis ports not mapped to host. ✅ Services use internal Docker DNS. |
| PHY-REV-01-03 | Volume Persistence Check | Constraint: Named volumes for state | ✅ Postgres data on named volume/PVC. ✅ Mage project on named volume/PVC. |

---

### Epic: REV-SCN-01 (Scenario View - Integration Verification)
**T-Shirt Size**: L  
**Objective**: Validate system cohesion through end-to-end scenarios.  
**Dependencies**: All previous Epics.  
**Risk**: HIGH - Components may work in isolation but fail when integrated.

#### Job Story (SPIN Format)
> When a new feature is ready for release [Circumstance],  
> I want to see evidence of successful end-to-end scenario execution [New Ability],  
> So that Drift Handling and Zero-Downtime mechanisms function correctly in production [Emotion].

| Task ID | Title | Technical Specifications | Acceptance Criteria |
|---------|-------|-------------------------|---------------------|
| SCN-REV-01-01 | Drift Detection Test Verification | Scenario: Handling Model Drift | ✅ Integration test simulates data drift. ✅ Verifies Mage trigger. ✅ Verifies new MOJO export. |
| SCN-REV-01-02 | Zero-Downtime Swap Verification | Scenario: Hot-swap during load | ✅ Load test runs during model swap. ✅ No 500 errors during swap. |

---

## Agentic Workflow

```
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ 1.SCOPE │───▶│2.LOGICAL│───▶│3.PROCESS│───▶│ 4.DEV   │
│  PR     │    │  View   │    │  View   │    │  View   │
└─────────┘    └─────────┘    └─────────┘    └────┬────┘
                                                   │
                                                   ▼
┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│8.REPORT │◀──│7.APPROVE│◀──│6.SCENARIO│◀──│5.PHYSICAL│
│         │    │         │    │  View   │    │  View   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
```

### Step 1: Scope PR
- Identify changed files and affected views
- Select applicable task IDs from Epics

### Step 2: Logical View Analysis
- Run `validate_schema_migration.py`
- Check JSONB/GIN compliance

### Step 3: Process View Analysis
- Run `detect_blocking_calls.py`
- Verify async/sync separation

### Step 4: Development View Analysis
- Run `verify_mojo_artifact.py`
- Check version pinning

### Step 5: Physical View Analysis
- Run `check_memory_allocation.py`
- Verify container configuration

### Step 6: Scenario View Analysis
- Verify integration test coverage
- Check E2E scenarios

### Step 7: Approval Decision
- Aggregate findings by severity
- Block on CRITICAL/HIGH

### Step 8: Generate Report
- Output structured findings
- Map to Task IDs for remediation

---

## Scripts

| Script | Superpower | Purpose |
|--------|------------|---------|
| `detect_blocking_calls.py` | Async Radar | AST-based detection of blocking calls in async |
| `validate_schema_migration.py` | Schema Drift | JSONB/GIN verification in migrations |
| `verify_mojo_artifact.py` | Artifact Integrity | MOJO vs POJO detection in pipelines |
| `check_memory_allocation.py` | Resource Sight | Container memory config validation |

### Usage

```bash
# Detect blocking calls in async functions
python scripts/detect_blocking_calls.py --source-dir ./src/api

# Validate schema migrations
python scripts/validate_schema_migration.py --migration-dir ./alembic/versions

# Verify MOJO artifacts in pipeline
python scripts/verify_mojo_artifact.py --pipeline-dir ./mage_pipeline

# Check memory allocation in Docker/K8s
python scripts/check_memory_allocation.py --compose-file ./docker-compose.yml
```

---

## Assets

| Asset | Purpose |
|-------|---------|
| `checklists/logical_view_review.md` | JSONB indexing, block atomicity |
| `checklists/process_view_review.md` | Async safety, connection pooling |
| `checklists/development_view_review.md` | MOJO mandate, version pinning |
| `checklists/physical_view_review.md` | Memory split, network isolation |
| `checklists/scenario_view_review.md` | Drift handling, zero-downtime |
| `templates/code_review_report.md` | Structured review output |
| `templates/spin_job_story.md` | SPIN format template |
| `templates/violation_report.md` | Architectural violation template |

---

## References

| Reference | Purpose |
|-----------|---------|
| `async_concurrency.md` | Event loop, GIL, run_in_executor |
| `mojo_vs_pojo.md` | Artifact comparison, size limits |
| `jsonb_indexing.md` | GIN indexes, TOAST, operators |
| `jvm_memory.md` | Heap vs Native, OOM prevention |

---

## Quick Start

```bash
# 1. Detect blocking calls
python scripts/detect_blocking_calls.py --source-dir ./src/api

# 2. Validate schema migrations
python scripts/validate_schema_migration.py --migration-dir ./alembic/versions

# 3. Verify MOJO artifacts
python scripts/verify_mojo_artifact.py --pipeline-dir ./mage_pipeline

# 4. Check container memory
python scripts/check_memory_allocation.py --compose-file ./docker-compose.yml

# 5. Generate review report
cat assets/templates/code_review_report.md
```

---

## Platform Context

This agent operates as the **Architectural Gate** enforcing the "Constitution" of the system:

- **Logical View**: Hybrid schema strategy, JSONB/GIN compliance
- **Process View**: Event loop protection, async/sync separation
- **Development View**: MOJO mandate, version consistency
- **Physical View**: Resource isolation, memory split
- **Scenario View**: Integration verification, drift handling