AIOX Quality Gate System Guide

EN | PT | ES

Comprehensive guide to the 3-layer quality gate system for Synkra AIOX.

Version: 2.1.0 Last Updated: 2025-12-01

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

graph LR
    subgraph "Quality Gates"
        L1[Layer 1: Pre-commit]
        L2[Layer 2: PR Automation]
        L3[Layer 3: Human Review]
    end

    Code --> L1
    L1 -->|Pass| L2
    L2 -->|Pass| L3
    L3 -->|Approved| Merge

    L1 -->|Fail| Fix1[Fix & Retry]
    L2 -->|Fail| Fix2[Fix & Retry]
    L3 -->|Reject| Fix3[Address Feedback]

    style L1 fill:#e3f2fd
    style L2 fill:#e8f5e9
    style L3 fill:#fff3e0

| 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 |

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

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 |

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

Assignment Strategies

| Strategy | Description | | --------------- | -------------------------------------------- | | auto | Assign based on file ownership and expertise | | manual | Manually assign reviewer | | round-robin | Rotate through team members |

Review Checklist

The strategic review checklist ensures reviewers cover key areas:

## 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 }}

GitLab CI

# .gitlab-ci.yml
stages:
  - layer1
  - layer2
  - layer3

layer1:
  stage: layer1
  script:
    - npm ci
    - aiox qa run --layer=1

layer2:
  stage: layer2
  script:
    - npm ci
    - aiox qa run --layer=2
  needs:
    - layer1

layer3:
  stage: layer3
  script:
    - aiox qa request-review
  needs:
    - layer2
  when: manual

Pre-commit Hook

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

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

Configuration Reference

Full Configuration Example

# quality-gate-config.yaml
version: '1.0'

# Layer 1: Pre-commit checks
layer1:
  enabled: true
  failFast: true
  checks:
    lint:
      enabled: true
      command: 'npm run lint'
      failOn: 'error'
      timeout: 60000
    test:
      enabled: true
      command: 'npm test'
      timeout: 300000
      coverage:
        enabled: true
        minimum: 80
    typecheck:
      enabled: true
      command: 'npm run typecheck'
      timeout: 120000

# Layer 2: PR Automation
layer2:
  enabled: true
  coderabbit:
    enabled: true
    command: 'coderabbit --prompt-only -t uncommitted'
    timeout: 900000
    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]

# Layer 3: Human Review
layer3:
  enabled: true
  requireSignoff: true
  assignmentStrategy: 'auto'
  defaultReviewer: '@architect'
  checklist:
    enabled: true
    template: 'strategic-review-checklist'
    minItems: 5
  signoff:
    required: true
    expiry: 86400000

# Reports
reports:
  location: '.aiox/qa-reports'
  format: 'json'
  retention: 30
  includeMetrics: true

# Status persistence
status:
  location: '.aiox/qa-status.json'
  updateOnChange: true

# Verbose output
verbose:
  enabled: false
  showCommands: true
  showOutput: true
  showTimings: true

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 |

AIOX Quality Gate System Guide

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

Configuration

Running Layer 2

Severity Levels

CodeRabbit Integration

Quinn (@qa) Integration

Layer 3: Human Review

Purpose

Configuration

Assignment Strategies

Review Checklist

Sign-off Process

CLI Commands

aiox qa run

aiox qa status

aiox qa report

aiox qa configure

CI/CD Integration

GitHub Actions

GitLab CI

Pre-commit Hook

Configuration Reference

Full Configuration Example

Troubleshooting

Layer 1 Failures

Layer 2 Failures

Layer 3 Issues

Related Documentation

`aiox qa run`

`aiox qa status`

`aiox qa report`

`aiox qa configure`