Production Readiness Guardian.

AI-powered frontend-backend contract validation for GitLab

Inspiration

We’ve all hit this fullstack pain point: a “simple” feature request touches backend routes, schemas, frontend API calls, TypeScript interfaces, and UI components across different folders and owners.
Manual tracing is slow, easy to skip, and hard to get right.

So code gets shipped, the MR looks fine, and then production fails on a silent contract mismatch:

Frontend sends:  { "username": "alice", "password": "s3cret" }
Backend expects: { "email": "...",      "password": "..." }

Result: 400 in production, zero warning during review.

Existing contract tools often require writing and maintaining contract files (high adoption friction), while many “auto-fix” tools overreach and patch high-risk issues that should stay human-reviewed (auth gaps, endpoint removals, architecture-level changes).

We built Production Readiness Guardian to solve both: contract validation inside the GitLab workflow, with safe, transparent auto-fixes that know their limits.

What It Does

Production Readiness Guardian is a Claude-powered agent system that covers the full frontend-backend contract lifecycle:

1) Pre-Code: Contract Advisor (Duo Chat Agent)

Before writing code, a developer asks:

analyze issue #15

The agent reads the issue and posts a Contract Impact Analysis directly on the issue:

Current Contract: endpoints, fields, types, auth requirements
Contract Impact: CONTRACT BREAK vs CONTRACT UPDATE NEEDED vs CHECK MANUALLY
Migration Checklist: ordered implementation steps (receiver before sender)
Architecture Diagram: Mermaid contract chain
Risk Assessment: LOW / MEDIUM / HIGH blast radius

2) Post-Code: Guardian Flow (5-Agent Pipeline)

When the MR is ready, five agents run in sequence:

$$ \text{Endpoint Validator} \rightarrow \text{Schema & Type Validator} \rightarrow \text{Breaking Change Detector} \rightarrow \text{Report Generator} \rightarrow \text{Auto Fixer} $$

Agent responsibilities

Endpoint Validator
Finds missing endpoints, method mismatches, missing auth, and unused routes.
Uses OpenAPI/Swagger/GraphQL as source of truth when present.
Schema & Type Validator
Traces runtime origins (not just TS annotations).
Catches field mismatches, missing required fields, unguarded optional access.
Breaking Change Detector
Reports only regressions introduced by the MR diff (not old debt).
Report Generator
Deduplicates findings, posts structured MR report, creates issues for CRITICAL findings, and labels MR:

Verdict	Condition	MR Label
BLOCKED	Any CRITICAL violation	`contract-violation::critical`
NEEDS ATTENTION	HIGH or MEDIUM only	`contract-violation::warning`
READY	LOW or none	`contract-violation::ready`

Auto Fixer
Applies fixes only for allowlisted safe categories:
- Type mismatch
- HTTP method mismatch
- Field name mismatch
- Unguarded field access
- Missing required field

Auto-Fix Safety Model

Before touching files, the Auto Fixer runs guardrails:

Repository-wide usage scan for target fields/endpoints
Abort if referenced in scripts/CI/infra-sensitive locations
Skip high-risk global keywords when:

$$ n > 50 $$

(where (n) = cross-directory matches)

Refuse UI-destructive edits (e.g., conditional render block removal)
If spec files exist, update spec + code atomically in one commit
Deliver changes as a Draft MR, never direct blind merge

How We Built It

Orchestration: GitLab Duo Workflow with explicit routing and context passing
Pre-code advisor: standalone Duo Chat agent prompt
Contract inference (no mandatory spec files):
- Backend routes/decorators
- Backend schemas/models
- Frontend API calls (fetch, axios, ky)
- Frontend types and component field usage
Spec-aware mode: prioritize OpenAPI/Swagger/GraphQL when available
Cross-framework design: structure-driven analysis, not framework-specific parser dependency

Demo Coverage

We built 3 demo stacks with pre-planted violations:

Project	Stack	Violations
nextjs-fastapi-demo	Next.js + FastAPI	HTTP method mismatch, unguarded field access, removed response field
react-express-demo	React + Express	Type mismatch (URL param string vs expected number), missing authentication
vue-django-demo	Vue + Django REST	Field name mismatch (`username` → `email`), missing required field (`user_id`)

Total issues: 7=5 (auto-fixable)+2 (manual)

Challenges We Ran Into

Defining strict boundaries for what AI may auto-fix safely
Preventing overconfident edits that should require human judgment
Passing rich context across five agents while keeping reports deduplicated and actionable
Reducing scope creep (no speculative findings, only real contract mismatches)
Enforcing runtime type tracing over “trust the annotation” behavior

Accomplishments We’re Proud Of

Pre-code impact prediction from issue text
Zero-setup adoption on existing codebases
Safe, explainable auto-fixes with explicit skips and reasons
Spec-aware atomic updates (spec + implementation together)
Cross-agent deduplication into one clear MR report
Workflow-native behavior integrated into GitLab review lifecycle

What We Learned

Chat-only AI is weak for cross-file contract reasoning without project context
Prompt design is system design: constraints and safety rules define behavior
The highest leverage moment is before code is written
Structured output matters as much as reasoning: in multi-agent plain-text handoffs, downstream quality depends on upstream formatting precision. Poorly formatted findings in one agent can break later deduplication.
Agentic systems need explicit limits; confidence without guardrails is dangerous