Quality Gates - Synkra AIOX

Overview

The AIOX Quality Gate System provides automated quality assurance through three progressive layers of validation. Each layer catches different types of issues at the appropriate stage of development.

The 3-Layer Architecture

Layer	Type	Speed	Purpose
Layer 1	Automated	~30s	Catch syntax, linting, type errors
Layer 2	AI-Assisted	~5m	Catch logic, security, patterns
Layer 3	Human	Variable	Strategic review, sign-off

Layer 1: Pre-commit Checks

Purpose

Fast, local checks that run before code is committed. Catches obvious issues immediately.

Checks Included

Check	Tool	Timeout	Description
Lint	ESLint	60s	Code style and best practices
Test	Jest	5m	Unit tests with coverage
TypeCheck	TypeScript	2m	Static type validation

Configuration

# .aiox-core/core/quality-gates/quality-gate-config.yaml
layer1:
  enabled: true
  failFast: true # Stop on first failure
  checks:
    lint:
      enabled: true
      command: 'npm run lint'
      failOn: 'error' # error | warning
      timeout: 60000 # 1 minute
    test:
      enabled: true
      command: 'npm test'
      timeout: 300000 # 5 minutes
      coverage:
        enabled: true
        minimum: 80
    typecheck:
      enabled: true
      command: 'npm run typecheck'
      timeout: 120000 # 2 minutes

Running Layer 1

# Run all Layer 1 checks
aiox qa run --layer=1

# Run specific check
aiox qa run --layer=1 --check=lint
aiox qa run --layer=1 --check=test
aiox qa run --layer=1 --check=typecheck

# Run with verbose output
aiox qa run --layer=1 --verbose

Expected Output

Layer 1: Pre-commit Checks
==========================

[1/3] Lint Check
  Running: npm run lint
  ✓ Passed (12.3s)
  No warnings or errors

[2/3] Test Check
  Running: npm test
  ✓ Passed (45.2s)
  Coverage: 87.3% (minimum: 80%)

[3/3] TypeCheck
  Running: npm run typecheck
  ✓ Passed (28.1s)
  0 errors

LAYER 1 PASSED (85.6s)

Layer 2: PR Automation

Purpose

AI-assisted code review that runs on pull requests. Catches deeper issues like logic errors, security vulnerabilities, and architectural problems.

Tools Integrated

Tool	Purpose	Blocking Severity
CodeRabbit	AI code review	CRITICAL
Quinn (@qa)	Automated QA review	CRITICAL

Severity Levels

Severity	Action	Description
CRITICAL	Block	Security vulnerability, data loss risk, breaking change
HIGH	Warn + Document	Performance issue, missing validation, anti-pattern
MEDIUM	Document	Code smell, improvement suggestion, minor risk
LOW	Ignore	Style preference, minor optimization

Configuration

# .aiox-core/core/quality-gates/quality-gate-config.yaml
layer2:
  enabled: true
  coderabbit:
    enabled: true
    command: 'coderabbit --prompt-only -t uncommitted'
    timeout: 900000 # 15 minutes
    blockOn:
      - CRITICAL
    warnOn:
      - HIGH
    documentOn:
      - MEDIUM
    ignoreOn:
      - LOW
  quinn:
    enabled: true
    autoReview: true
    agentPath: '.claude/commands/AIOX/agents/qa.md'
    severity:
      block: ['CRITICAL']
      warn: ['HIGH', 'MEDIUM']

Running Layer 2

# Run all Layer 2 checks
aiox qa run --layer=2

# Run CodeRabbit only
aiox qa run --layer=2 --tool=coderabbit

# Run Quinn (@qa) review
aiox qa run --layer=2 --tool=quinn

CodeRabbit Integration

CodeRabbit performs AI-powered code review with these focus areas:

Security vulnerabilities
Performance issues
Code quality and maintainability
Best practices violations
Documentation completeness

# Manual CodeRabbit run
coderabbit --prompt-only -t uncommitted

# With specific paths
coderabbit --files "src/**/*.js" --prompt-only

Quinn (@qa) Integration

The QA agent performs automated review focused on:

Test coverage adequacy
Edge case handling
Error handling completeness
Acceptance criteria validation

// Programmatic Quinn invocation
const QualityGateManager = require('./.aiox-core/core/quality-gates/quality-gate-manager');
const manager = new QualityGateManager();
const result = await manager.runQuinnReview(pullRequestId);

Layer 3: Human Review

Purpose

Strategic human review for final sign-off. Ensures business requirements are met and architectural decisions are sound.

Configuration

# .aiox-core/core/quality-gates/quality-gate-config.yaml
layer3:
  enabled: true
  requireSignoff: true
  assignmentStrategy: 'auto' # auto | manual | round-robin
  defaultReviewer: '@architect'
  checklist:
    enabled: true
    template: 'strategic-review-checklist'
    minItems: 5
  signoff:
    required: true
    expiry: 86400000 # 24 hours in ms

Review Checklist

## Strategic Review Checklist

### Architecture

- [ ] Changes align with system architecture
- [ ] No unauthorized dependencies introduced
- [ ] Backwards compatibility maintained

### Security

- [ ] No sensitive data exposed
- [ ] Input validation present
- [ ] Authentication/authorization correct

### Quality

- [ ] Code is maintainable and readable
- [ ] Tests are comprehensive
- [ ] Documentation updated

### Business

- [ ] Acceptance criteria met
- [ ] User experience considered
- [ ] Performance acceptable

Sign-off Process

# Request human review
aiox qa request-review --pr=123

# Sign off on review
aiox qa signoff --pr=123 --reviewer="@architect"

# Check sign-off status
aiox qa signoff-status --pr=123

CLI Commands

`aiox qa run`

Run quality gate checks.

# Run all layers sequentially
aiox qa run

# Run specific layer
aiox qa run --layer=1
aiox qa run --layer=2
aiox qa run --layer=3

# Run with options
aiox qa run --verbose          # Detailed output
aiox qa run --fail-fast        # Stop on first failure
aiox qa run --continue-on-fail # Continue despite failures

`aiox qa status`

Check current quality gate status.

# Get overall status
aiox qa status

# Get status for specific layer
aiox qa status --layer=1

# Get status for PR
aiox qa status --pr=123

Output:

Quality Gate Status
===================

Layer 1: Pre-commit
  Lint:      ✓ Passed
  Test:      ✓ Passed (87.3% coverage)
  TypeCheck: ✓ Passed

Layer 2: PR Automation
  CodeRabbit: ✓ Passed (0 critical, 2 medium)
  Quinn:      ✓ Passed

Layer 3: Human Review
  Status:    Pending
  Assigned:  @architect
  Expires:   2025-12-02 12:00:00

Overall: PENDING REVIEW

`aiox qa report`

Generate quality gate report.

# Generate report
aiox qa report

# Export to file
aiox qa report --output=qa-report.json
aiox qa report --format=markdown --output=qa-report.md

`aiox qa configure`

Configure quality gate settings.

# Interactive configuration
aiox qa configure

# Set specific options
aiox qa configure --layer1.coverage.minimum=90
aiox qa configure --layer2.coderabbit.enabled=false
aiox qa configure --layer3.requireSignoff=true

CI/CD Integration

GitHub Actions

# .github/workflows/quality-gate.yml
name: Quality Gate

on:
  pull_request:
    branches: [main, develop]

jobs:
  layer1:
    name: Layer 1 - Pre-commit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: aiox qa run --layer=1

  layer2:
    name: Layer 2 - PR Automation
    needs: layer1
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: aiox qa run --layer=2
        env:
          CODERABBIT_API_KEY: ${{ secrets.CODERABBIT_API_KEY }}

  layer3:
    name: Layer 3 - Human Review
    needs: layer2
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: aiox qa request-review --pr=${{ github.event.pull_request.number }}

Pre-commit Hook

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

aiox qa run --layer=1 --fail-fast

Troubleshooting

Layer 1 Failures

Issue	Solution
Lint errors	Run `npm run lint -- --fix` to auto-fix
Test failures	Check test output, update tests or fix code
TypeCheck errors	Review type annotations, fix type mismatches
Timeout	Increase timeout in config or optimize tests

Layer 2 Failures

Issue	Solution
CodeRabbit critical	Address security/breaking change issues
CodeRabbit timeout	Check network, try manual run
Quinn blocked	Review @qa feedback, update code

Layer 3 Issues

Issue	Solution
No reviewer assigned	Set defaultReviewer in config
Sign-off expired	Request new review
Checklist incomplete	Complete all required items

Best Practices

Layer 1

Run locally before commit - Don’t wait for pre-commit hook
Fix issues immediately - Don’t accumulate technical debt
Keep tests fast - Optimize slow tests
Use caching - Leverage .eslintcache and .tsbuildinfo

Layer 2

Address critical issues first - They block the merge
Document medium issues - Create follow-up stories
Review Quinn feedback - AI catches patterns you might miss
Keep PRs small - Easier to review, faster CI

Layer 3

Complete checklist thoroughly - Each item has a purpose
Ask questions - Don’t approve what you don’t understand
Consider long-term impact - Not just immediate functionality
Provide constructive feedback - Help improve code quality

Performance Optimization

Layer 1 Speed

First run: ~10-15s (no cache)
Subsequent runs: Less than 5s (cached)
Optimization: Clear caches if corrupted

Layer 2 Speed

CodeRabbit: 2-5 minutes typical
Quinn: 1-3 minutes typical
Optimization: Run in parallel when possible

Layer 3 Speed

Human review: Variable (hours to days)
Optimization: Clear checklist, good PR description

Getting Started

Development

Extensions

​Overview

​The 3-Layer Architecture

​Layer 1: Pre-commit Checks

​Purpose

​Checks Included

​Configuration

​Running Layer 1

​Expected Output

​Layer 2: PR Automation

​Purpose

​Tools Integrated

​Severity Levels

​Configuration

​Running Layer 2

​CodeRabbit Integration

​Quinn (@qa) Integration

​Layer 3: Human Review

​Purpose

​Configuration

​Review Checklist

​Sign-off Process

​CLI Commands

​aiox qa run

​aiox qa status

​aiox qa report

​aiox qa configure

​CI/CD Integration

​GitHub Actions

​Pre-commit Hook

​Troubleshooting

​Layer 1 Failures

​Layer 2 Failures

​Layer 3 Issues

​Best Practices

​Layer 1

​Layer 2

​Layer 3

​Performance Optimization

​Layer 1 Speed

​Layer 2 Speed

​Layer 3 Speed

Build docs developers (and LLMs) love

Overview

The 3-Layer Architecture

Layer 1: Pre-commit Checks

Purpose

Checks Included

Configuration

Running Layer 1

Expected Output

Layer 2: PR Automation

Purpose

Tools Integrated

Severity Levels

Configuration

Running Layer 2

CodeRabbit Integration

Quinn (@qa) Integration

Layer 3: Human Review

Purpose

Configuration

Review Checklist

Sign-off Process

CLI Commands

`aiox qa run`

`aiox qa status`

`aiox qa report`

`aiox qa configure`

CI/CD Integration

GitHub Actions

Pre-commit Hook

Troubleshooting

Layer 1 Failures

Layer 2 Failures

Layer 3 Issues

Best Practices

Layer 1

Layer 2

Layer 3

Performance Optimization

Layer 1 Speed

Layer 2 Speed

Layer 3 Speed