aios-core
Version:
Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework
557 lines (437 loc) • 19.7 kB
Markdown
# Quality Gates Specification v4.2
**Version:** 2.1.0
**Last Updated:** 2025-12-09
**Status:** Official Standard
**Related:** Sprint 3 Implementation
## 📋 Table of Contents
- [Overview](#overview)
- [3-Layer Architecture](#3-layer-architecture)
- [Layer 1: Pre-commit](#layer-1-pre-commit)
- [Layer 2: PR Automation](#layer-2-pr-automation)
- [Layer 3: Human Review](#layer-3-human-review)
- [Configuration Guide](#configuration-guide)
- [CodeRabbit Self-Healing](#coderabbit-self-healing)
- [Metrics & Impact](#metrics--impact)
## Overview
### Purpose
The Quality Gates 3-Layer system ensures code quality through progressive automated validation, catching 80% of issues automatically and focusing human review on strategic decisions.
### Design Principles
1. **Shift Left** - Catch issues as early as possible
2. **Progressive Depth** - Each layer adds more comprehensive checks
3. **Automation First** - Humans focus on what humans do best
4. **Fast Feedback** - Immediate response at each layer
5. **Non-Blocking Default** - Warnings vs. errors where appropriate
### Architecture Diagram
```
┌─────────────────────────────────────────────────────────────────────────┐
│ QUALITY GATES WORKFLOW │
│ │
│ Developer │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ LAYER 1: PRE-COMMIT │ │
│ │ ════════════════════ │ │
│ │ Trigger: File save, git commit │ │
│ │ Time: < 5 seconds │ │
│ │ Catches: 30% of issues │ │
│ │ │ │
│ │ ✓ ESLint (syntax, patterns) │ │
│ │ ✓ Prettier (formatting) │ │
│ │ ✓ TypeScript (type checking) │ │
│ │ ✓ Unit tests (changed files only) │ │
│ │ │ │
│ │ Blocking: Yes (can't commit if fails) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ PASS? │ │
│ ▼ │
│ git commit │
│ git push │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ LAYER 2: PR AUTOMATION │ │
│ │ ══════════════════════ │ │
│ │ Trigger: PR creation, PR update │ │
│ │ Time: < 3 minutes │ │
│ │ Catches: Additional 50% (80% cumulative) │ │
│ │ │ │
│ │ ✓ CodeRabbit AI review │ │
│ │ ✓ Integration tests │ │
│ │ ✓ Coverage analysis (threshold: 80%) │ │
│ │ ✓ Security scan (npm audit, Snyk) │ │
│ │ ✓ Performance benchmarks │ │
│ │ ✓ Documentation validation │ │
│ │ │ │
│ │ Blocking: Yes (required checks for merge) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ PASS? │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ LAYER 3: HUMAN REVIEW │ │
│ │ ═════════════════════ │ │
│ │ Trigger: Layer 2 passes │ │
│ │ Time: 30 min - 2 hours │ │
│ │ Catches: Final 20% (100% cumulative) │ │
│ │ │ │
│ │ □ Architecture alignment │ │
│ │ □ Business logic correctness │ │
│ │ □ Edge cases coverage │ │
│ │ □ Documentation quality │ │
│ │ □ Security best practices │ │
│ │ □ Strategic decisions │ │
│ │ │ │
│ │ Blocking: Yes (final approval required) │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │ │
│ APPROVE │
│ │ │
│ ▼ │
│ MERGE │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
## Layer 1: Pre-commit
### Purpose
Catch syntax errors, formatting issues, and simple bugs immediately during development, before code leaves the developer's machine.
### Checks
| Check | Tool | Config File | Blocking |
|-------|------|-------------|----------|
| Linting | ESLint | `.eslintrc.json` | Yes |
| Formatting | Prettier | `.prettierrc` | Yes |
| Type Checking | TypeScript | `tsconfig.json` | Yes |
| Unit Tests | Jest | `jest.config.js` | Yes |
| Commit Message | commitlint | `commitlint.config.js` | Yes |
### Configuration
#### .husky/pre-commit
```bash
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
# Run lint-staged for incremental checks
npx lint-staged
# Type check (full project)
npm run typecheck
# Run tests for changed files only
npm test -- --onlyChanged --passWithNoTests
```
#### .lintstagedrc.json
```json
{
"*.{js,jsx,ts,tsx}": [
"eslint --fix",
"prettier --write"
],
"*.{json,md,yaml,yml}": [
"prettier --write"
],
"*.md": [
"markdownlint --fix"
]
}
```
#### package.json scripts
```json
{
"scripts": {
"lint": "eslint . --ext .js,.jsx,.ts,.tsx",
"lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
"format": "prettier --write .",
"typecheck": "tsc --noEmit",
"test": "jest",
"test:changed": "jest --onlyChanged",
"prepare": "husky install"
}
}
```
### Expected Results
- **Time:** < 5 seconds per commit
- **Issues Caught:** ~30% of all potential issues
- **Developer Experience:** Immediate feedback, no context switching
## Layer 2: PR Automation
### Purpose
Run comprehensive automated checks on every PR, including AI-powered code review, integration tests, and security scanning.
### Checks
| Check | Tool | Threshold | Blocking |
|-------|------|-----------|----------|
| AI Code Review | CodeRabbit | N/A (suggestions) | No* |
| Integration Tests | Jest | 100% pass | Yes |
| Coverage | Jest | 80% minimum | Yes |
| Security Audit | npm audit | No high/critical | Yes |
| Lint | ESLint | 0 errors | Yes |
| Type Check | TypeScript | 0 errors | Yes |
| Build | npm/webpack | Success | Yes |
*CodeRabbit suggestions are non-blocking but tracked.
### Configuration
#### .github/workflows/quality-gates-pr.yml
```yaml
name: Quality Gates PR
on:
pull_request:
branches: [main, develop]
push:
branches: [main, develop]
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
quality-gates:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Lint
run: npm run lint
- name: Type check
run: npm run typecheck
- name: Test with coverage
run: npm test -- --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80,"statements":80}}'
- name: Security audit
run: npm audit --audit-level=high
- name: Build
run: npm run build
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
file: ./coverage/lcov.info
fail_ci_if_error: false
```
#### .github/coderabbit.yaml
```yaml
# CodeRabbit Configuration
language: "en"
tone_instructions: "Be constructive and helpful. Focus on bugs, security, and best practices."
early_access: false
reviews:
profile: "chill"
request_changes_workflow: false
high_level_summary: true
poem: false
review_status: true
collapse_walkthrough: false
auto_review:
enabled: true
drafts: false
base_branches:
- main
- develop
path_filters:
- path: "**/*.test.ts"
instructions: "Focus on test coverage and edge cases"
- path: "**/*.md"
instructions: "Check for broken links, typos, and clarity"
- path: ".aios-core/**"
instructions: "Ensure consistency with framework standards"
chat:
auto_reply: true
```
### Expected Results
- **Time:** < 3 minutes per PR update
- **Issues Caught:** Additional 50% (80% cumulative)
- **Developer Experience:** Detailed feedback before human review
## Layer 3: Human Review
### Purpose
Strategic review by humans focusing on architecture, business logic, and edge cases that automated tools cannot evaluate.
### Review Focus
| Area | Reviewer | What to Check |
|------|----------|---------------|
| Architecture | @architect, Tech Lead | Alignment with patterns, scalability |
| Business Logic | PO, Domain Expert | Correctness, edge cases |
| Security | Security Champion | Best practices, vulnerabilities |
| Documentation | Tech Writer | Clarity, completeness |
| UX Impact | UX Expert | User-facing changes |
### CODEOWNERS Configuration
```
# CODEOWNERS - Layer 3 Human Review Assignments
# Default reviewers
* @team-leads
# Architecture-sensitive areas
/.aios-core/core/ @architect @senior-devs
/docs/architecture/ @architect
/src/core/ @senior-devs
# Security-sensitive areas
/src/auth/ @security-team
/.github/workflows/ @devops-team
**/security*.* @security-team
# Documentation
*.md @tech-writers
/docs/ @tech-writers
# Configuration files
package.json @senior-devs
tsconfig.json @senior-devs
.eslintrc.* @senior-devs
# Squads (modular areas)
/squads/etl/ @data-team
/squads/creator/ @content-team
```
### Review Checklist
```markdown
## Human Review Checklist
### Architecture
- [ ] Changes align with module boundaries
- [ ] Dependencies flow correctly (no circular)
- [ ] No breaking changes without migration path
### Business Logic
- [ ] Requirements correctly implemented
- [ ] Edge cases handled
- [ ] Error scenarios covered
### Security
- [ ] No hardcoded secrets
- [ ] Input validation present
- [ ] Authentication/authorization correct
### Performance
- [ ] No N+1 queries
- [ ] Caching considered
- [ ] Large operations async
### Documentation
- [ ] README updated if needed
- [ ] API documentation current
- [ ] Breaking changes documented
### Tests
- [ ] Critical paths covered
- [ ] Edge cases tested
- [ ] Mocks appropriate
```
### Expected Results
- **Time:** 30 min - 2 hours per PR
- **Issues Caught:** Final 20% (100% cumulative)
- **Focus:** Strategic decisions, not syntax
## Configuration Guide
### Initial Setup
```bash
# 1. Install dependencies
npm install -D husky lint-staged eslint prettier typescript jest @commitlint/cli @commitlint/config-conventional
# 2. Initialize Husky
npx husky install
# 3. Add pre-commit hook
npx husky add .husky/pre-commit "npx lint-staged && npm run typecheck && npm test -- --onlyChanged"
# 4. Add commit-msg hook (optional)
npx husky add .husky/commit-msg "npx --no -- commitlint --edit $1"
# 5. Update package.json
npm pkg set scripts.prepare="husky install"
```
### Customization
#### Adjusting Thresholds
```json
// jest.config.js
module.exports = {
coverageThreshold: {
global: {
branches: 80, // Adjust as needed
functions: 80,
lines: 80,
statements: 80
}
}
};
```
#### Skipping Checks (Emergency Only)
```bash
# Skip Layer 1 (use sparingly!)
git commit --no-verify -m "emergency: fix production issue"
# Layer 2: Use [skip ci] in commit message
git commit -m "docs: update readme [skip ci]"
```
## CodeRabbit Self-Healing
### Story Type Analysis
CodeRabbit automatically adjusts review focus based on story type:
| Story Type | Review Focus | Priority Checks |
|------------|--------------|-----------------|
| 🔧 Infrastructure | Configuration, CI/CD | Security, backwards compatibility |
| 💻 Feature | Business logic, UX | Tests, documentation |
| 📖 Documentation | Clarity, accuracy | Links, terminology |
| ✅ Validation | Test coverage | Edge cases |
| 🐛 Bug Fix | Root cause, regression | Tests, side effects |
### Path-Based Instructions
```yaml
# .github/coderabbit.yaml
reviews:
path_instructions:
- path: "**/*.test.ts"
instructions: |
Focus on:
- Test coverage completeness
- Edge case handling
- Mock appropriateness
- Assertion quality
- path: ".aios-core/docs/standards/**"
instructions: |
Verify:
- Terminology uses 'Squad' not 'Squad'
- All internal links work
- Version numbers are v4.2
- path: "squads/**"
instructions: |
Check:
- squad.yaml manifest is valid
- peerDependency on @aios/core declared
- Follows Squad structure conventions
- path: ".github/workflows/**"
instructions: |
Review:
- No hardcoded secrets
- Proper timeout settings
- Concurrency configuration
- Security best practices
```
## Metrics & Impact
### Before Quality Gates (v2.0)
| Metric | Value |
|--------|-------|
| Issues caught automatically | 0% |
| Average review time | 2-4 hours per PR |
| Issues escaping to production | ~15% |
| Developer context switches | High |
### After Quality Gates (v4.2)
| Metric | Value | Improvement |
|--------|-------|-------------|
| Issues caught automatically | 80% | **∞** |
| Average review time | 30 min per PR | **75% reduction** |
| Issues escaping to production | <5% | **67% reduction** |
| Developer context switches | Low | **Significant** |
### Layer Breakdown
```
┌─────────────────────────────────────────────────────────────────────────┐
│ ISSUE DETECTION BY LAYER │
│ │
│ Layer 1 (Pre-commit) │
│ ████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 30% │
│ │
│ Layer 2 (PR Automation) │
│ ████████████████████████████████████████████████████████░░░░ 80% │
│ (includes Layer 1 + additional 50%) │
│ │
│ Layer 3 (Human Review) │
│ ████████████████████████████████████████████████████████████ 100% │
│ (includes Layer 1 + Layer 2 + final 20%) │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
## Related Documents
- [AIOS-LIVRO-DE-OURO-V2.1-COMPLETE.md](./AIOS-LIVRO-DE-OURO-V2.1-COMPLETE.md)
- [CodeRabbit Integration Decisions](../../docs/architecture/coderabbit-integration-decisions.md)
- [STORY-TEMPLATE-V2-SPECIFICATION.md](./STORY-TEMPLATE-V2-SPECIFICATION.md)
**Last Updated:** 2025-12-09
**Version:** 2.1.0
**Maintainer:** @qa (Quinn)