grimoire-framework 1.0.0

package/.grimoire/docs/standards/QUALITY-GATES-SPECIFICATION.md

@@ -0,0 +1,558 @@
+# Quality Gates Specification v4.0.4
+
+**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: ".grimoire/**"
+      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
+/.grimoire/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: ".grimoire/docs/standards/**"
+      instructions: |
+        Verify:
+        - Terminology uses 'Squad' not 'Squad'
+        - All internal links work
+        - Version numbers are v4.0.4
+
+    - path: "squads/**"
+      instructions: |
+        Check:
+        - squad.yaml manifest is valid
+        - peerDependency on @grimoire/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.0.4)
+
+| 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
+
+- [grimoire-LIVRO-DE-OURO-V2.1-COMPLETE.md](./grimoire-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)
+
+