> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Quality Gates

> Comprehensive guide to the 3-layer quality gate system for ensuring code quality

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

```yaml theme={null}
# .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

```bash theme={null}
# 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

```yaml theme={null}
# .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

```bash theme={null}
# 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

```bash theme={null}
# 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

```javascript theme={null}
// 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

```yaml theme={null}
# .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

```markdown theme={null}
## 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

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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

```yaml theme={null}
# .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

```bash theme={null}
# .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

1. **Run locally before commit** - Don't wait for pre-commit hook
2. **Fix issues immediately** - Don't accumulate technical debt
3. **Keep tests fast** - Optimize slow tests
4. **Use caching** - Leverage `.eslintcache` and `.tsbuildinfo`

### Layer 2

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

### Layer 3

1. **Complete checklist thoroughly** - Each item has a purpose
2. **Ask questions** - Don't approve what you don't understand
3. **Consider long-term impact** - Not just immediate functionality
4. **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