Quality Gates - Code Quality Enforcement

Configurable, language-agnostic quality gates for preventing functional duplication, architectural drift, and code quality regression. These gates work cohesively to maintain code quality across development, CI/CD, and production environments, supporting Python, Go, Java, C#, Ruby, PHP, C++, Kotlin, Swift, Scala, Rust, and more.

Priority Focus

Quality gates block commits that degrade code quality while enabling controlled development workflows through waiver integration and intelligent cache management.

What Quality Gates Check

1. Functional Duplication Prevention (check-functional-duplication.mjs)

Blocks: Increases in functional duplication beyond thresholds

• More than 692 duplicate struct names (CRITICAL - compilation conflicts)
• More than 200 duplicate function names (NEW - business logic duplication)
• More than 100 duplicate trait names (NEW - interface duplication)
• More than 20 problematic duplicate filenames (excluding language convention files)
• Convention files across languages (lib.rs, mod.rs, init.py, index.ts, etc.) are expected and allowed

2. Naming Conventions (check-naming.mjs)

Blocks: Files/structs with banned modifiers indicating functional duplication

• enhanced-*, unified-*, new-*, final-*, copy-*, revamp-*, improved-*
• Purpose-first canonical names
• Covers 20+ file extensions (.rs, .py, .go, .java, .cs, .rb, .php, .cpp, .kt, .swift, .scala, etc.)
• Convention files across languages (lib.rs, mod.rs, init.py, index.ts, etc.) are ignored

3. Simplification Detection (check-simplification.mjs)

Blocks: Files where implementations are replaced with stubs or oversimplified code patterns

• LOC decrease >= 30% paired with new stub patterns (pass, TODO, NotImplementedError, return null, unimplemented!(), throw, etc.)
• Compares HEAD vs staged (commit) or merge-base vs HEAD (push/ci)
• Detects renamed-and-simplified files via git diff --find-renames
• Warns on large deletions even without stubs
• Language-aware stub detection using commentStyleFor(ext) from language-support.mjs

4. File Sprawl Detection (in check-naming.mjs)

Blocks: Common file sprawl patterns from AI agents

• Shadow files (*-enhanced.*, *-final.*, *-v2.*, *-copy.*)
• Virtual environment sprawl (*venv*, .venv, env/)
• Documentation sprawl (*-summary.md, *-recap.md, *-plan.md)
• Build artifact directories are excluded from checks: node_modules, target, dist, build, __pycache__, .tox, vendor, obj, .gradle, bin, .next, .nuxt, and others

5. God Object Prevention (check-god-objects.mjs)

Blocks: Files exceeding size thresholds across all supported languages

• 3,000+ SLOC: Severe god objects (immediate intervention required)
• 2,000+ SLOC: Critical god objects (CI/CD block)
• 1,500+ SLOC: Warning (allows but flags for decomposition)
• <1,500 SLOC: Target for long-term maintainability

Multi-language SLOC counting strips comments and blank lines per language. No longer limited to Rust; checks all code files recognized by language-support.mjs.

Shared Language Support (language-support.mjs)

A shared module used by all gates to provide consistent multi-language behavior:

• CODE_EXTENSIONS -- Map of file extensions to language metadata (.rs, .py, .go, .java, .cs, .rb, .php, .cpp, .kt, .swift, .scala, .ts, .js, etc.)
• CONVENTION_FILES -- Set of known convention filenames that are expected duplicates (lib.rs, mod.rs, __init__.py, index.ts, index.js, main.go, etc.)
• commentStyleFor(ext) -- Returns the comment syntax (line and block delimiters) for a given file extension, used by SLOC counting and stub detection

Gates import from this module rather than maintaining their own extension lists.

Key Features

Waiver System Integration

Quality gates integrate with CAWS CLI waivers for controlled exceptions:

# Create waiver for architectural work
caws waivers create \
  --title="Emergency hotfix waiver" \
  --reason=emergency_hotfix \
  --gates=hidden-todo \
  --expires-at=2025-12-31T23:59:59Z

# Quality gates automatically apply waivers
node run-quality-gates.mjs  # Waived violations won't block commits

Waiver Display:

ACTIVE WAIVERS (1):
   WV-0001: Extended CAWS feature implementation scope (63 days left)
      Gates: budget_limit
      Reason: experimental_feature

WAIVED VIOLATIONS (2) - ALLOWED:
   hidden-todo: PLACEHOLDER - Real implementation needed
   Waived by: WV-0001 (Emergency hotfix waiver)

Context-Aware File Scoping

Quality gates scope the files they check based on the execution context:

• Commit context: Checks staged files only
• Push context: Checks files changed since the merge-base (not all tracked files), providing focused feedback on the actual changeset
• CI context: Same as push context, scoped to changed-since-base files

Timeout Scaling

Gate timeouts scale with context to accommodate larger file sets:

• Commit context: Base timeout (default)
• Push context: 2x base timeout
• CI context: 4x base timeout

Intelligent Cache Management

Quality gates automatically manage caches for performance and reliability:

• File Change Detection: Clears caches when files change
• Successful Exit Cleanup: Clears temporary caches on completion
• Crash Recovery: Automatic cleanup on unexpected termination
• Stale Lock Prevention: Removes locks older than 5 minutes

How It Works

Quick Start with npx

# Run quality gates via npx (no installation needed)
npx @paths.design/quality-gates

# CI mode
npx @paths.design/quality-gates --ci

# Specific gates only
npx @paths.design/quality-gates --gates=naming,duplication

# JSON output
npx @paths.design/quality-gates --json

Note: The package exposes the binary as caws-quality-gates, so you can also use:

npx @paths.design/quality-gates caws-quality-gates

Pre-commit Hook (Local Development)

# Automatic - runs before every commit
Quality gates passed - proceeding with commit
# OR
Quality gates failed - commit blocked
Fix the violations above before committing

CI/CD Pipeline

• Job: Quality Gates (Crisis Response)
• Runs: Before tests, after linting
• Blocks: PR merges if quality violations detected
• Reports: Detailed violation breakdown in CI logs

Current Functional Duplication Baselines

| Metric | Current | Threshold | Status | Priority | | ------------------------------------------- | -------- | --------- | ----------- | -------- | | Duplicate struct names | 692+ | ≤692 | CRITICAL | HIGH | | Duplicate function names | ~200 | ≤200 | CRITICAL | HIGH | | Duplicate trait names | ~100 | ≤100 | CRITICAL | HIGH | | Problematic filename duplicates | ~20 | ≤20 | MODERATE | MEDIUM | | Convention file duplicates (lib.rs, init.py, etc.) | ~128 | N/A | EXPECTED | NONE | | God objects >3K LOC | 11 | 0 | CRITICAL | HIGH | | God objects >2K LOC | Multiple | 0 | CRITICAL | HIGH |

Focus: Functional duplication must decrease. Language convention files are expected duplicates.

Usage

Installation

From npm (recommended):

# Install as dev dependency
npm install --save-dev @paths.design/quality-gates

# Or install globally
npm install -g @paths.design/quality-gates

In CAWS monorepo:

# Use local package directly
node packages/quality-gates/run-quality-gates.mjs

Quick Start

Via npx (recommended - no installation needed):

# Run all quality gates (development mode)
npx @paths.design/quality-gates

# Run all gates in CI mode (strict enforcement)
npx @paths.design/quality-gates --ci

# Get machine-readable JSON output
npx @paths.design/quality-gates --json

# Run only specific gates
npx @paths.design/quality-gates --gates=naming,duplication

With npm package:

# Run all quality gates (development mode)
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs

# Or if installed globally
caws-quality-gates

# Run all gates in CI mode (strict enforcement)
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci

# Get machine-readable JSON output
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --json

# Run only specific gates
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --gates=naming,duplication

In monorepo (development):

# Run all quality gates (development mode)
node packages/quality-gates/run-quality-gates.mjs

# Run all gates in CI mode (strict enforcement)
node packages/quality-gates/run-quality-gates.mjs --ci

# Get machine-readable JSON output
node packages/quality-gates/run-quality-gates.mjs --json

# Run only specific gates
node packages/quality-gates/run-quality-gates.mjs --gates=naming,duplication

Usage Scenarios

1. Local Development (Interactive)

With npm package:

# Standard development check
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs

# Focus on specific areas during development
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --gates=naming
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --gates=god_objects
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --gates=duplication

In monorepo:

# Standard development check
node packages/quality-gates/run-quality-gates.mjs

# Focus on specific areas during development
node packages/quality-gates/run-quality-gates.mjs --gates=naming
node packages/quality-gates/run-quality-gates.mjs --gates=god_objects
node packages/quality-gates/run-quality-gates.mjs --gates=duplication

2. CI/CD Integration

Via npx (recommended - no installation needed):

# GitHub Actions / CI pipeline
npx @paths.design/quality-gates --ci

# With step summary (GitHub Actions)
GITHUB_STEP_SUMMARY=/tmp/summary.md npx @paths.design/quality-gates --ci

# Matrix builds (test specific gates)
npx @paths.design/quality-gates --ci --gates=naming
npx @paths.design/quality-gates --ci --gates=duplication

With npm package:

# GitHub Actions / CI pipeline
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci

# With step summary (GitHub Actions)
GITHUB_STEP_SUMMARY=/tmp/summary.md node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci

# Matrix builds (test specific gates)
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci --gates=naming
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci --gates=duplication

In monorepo:

# GitHub Actions / CI pipeline
node packages/quality-gates/run-quality-gates.mjs --ci

# With step summary (GitHub Actions)
GITHUB_STEP_SUMMARY=/tmp/summary.md node packages/quality-gates/run-quality-gates.mjs --ci

# Matrix builds (test specific gates)
node packages/quality-gates/run-quality-gates.mjs --ci --gates=naming
node packages/quality-gates/run-quality-gates.mjs --ci --gates=duplication

3. CAWS Integration

# As part of CAWS workflow
caws quality-gates --run-all

# CAWS with specific gates
caws quality-gates --gates=naming,god_objects

# CAWS in CI mode
caws quality-gates --ci --json

4. Pre-commit Hook

Via npx:

# Setup pre-commit hook
echo '#!/bin/bash
npx @paths.design/quality-gates --ci' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

With npm package:

# Setup pre-commit hook
echo '#!/bin/bash
node node_modules/@paths.design/quality-gates/run-quality-gates.mjs --ci' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

In monorepo:

# Setup pre-commit hook
echo '#!/bin/bash
node packages/quality-gates/run-quality-gates.mjs --ci' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Note: CAWS scaffold automatically sets up pre-commit hooks that detect and use the installed package.

Command Line Options

| Option | Description | Example | | ---------------- | -------------------------------------- | ---------------------------- | | --ci | Strict CI mode (blocks on warnings) | --ci | | --json | Machine-readable JSON output | --json | | --gates=<list> | Run only specific gates | --gates=naming,duplication | | --fix | Attempt automatic fixes (experimental) | --fix |

Valid Gate Names

• naming - Naming conventions, banned modifiers, and file sprawl detection
• code_freeze - Code freeze compliance (blocks new features)
• duplication - Functional duplication detection
• god_objects - God object size limits
• hidden-todo - Hidden incomplete implementations
• documentation - Documentation quality checks
• simplification - Detects implementations replaced with stubs
• placeholders - Placeholder governance (explicit degradations)

Output Formats

Standard Output (Development)

Running Quality Gates - Crisis Response Mode
==================================================
Context: COMMIT (staged files only)
Files to check: 13
==================================================

Checking naming conventions...
   No problematic naming patterns found

Checking duplication...
   Checking functional duplication...
   0 functional duplication findings (warn mode)

JSON Output (Automation)

{
  "timestamp": "2025-10-28T22:01:19.090Z",
  "context": "commit",
  "files_scoped": 13,
  "warnings": [],
  "violations": []
}

GitHub Actions Summary

# Quality Gates

- Context: commit
- Files scoped: 13
- Violations: 0
- Warnings: 1

## Violations

- **duplication/violation_type**: Description of issue

When Gates Block Commits

Naming Violations

FILENAME_BANNED_MODIFIER: iterations/v3/src/enhanced_parser.rs
   Filename contains banned modifier: enhanced
   Rule: No duplicate "enhanced/unified/new/final" modules

Fix: Rename to purpose-first canonical name (e.g., parser.rs)

Functional Duplication Regression

STRUCT_DUPLICATION_REGRESSION
   Duplicate struct names increased from 692 to 700
   Issue: Functional duplication must not increase

FUNCTION_DUPLICATION_REGRESSION
   Duplicate function names increased from 200 to 210
   Issue: Business logic duplication detected

TRAIT_DUPLICATION_REGRESSION
   Duplicate trait names increased from 100 to 105
   Issue: Interface duplication detected

Fix: Extract common traits, consolidate duplicate business logic, unify interfaces

God Object Violations

SEVERE_GOD_OBJECT
   File: council/src/intelligent_edge_case_testing.rs
   Size: 6348 LOC
   Limit: 3000 LOC
   Issue: SEVERE god object: 6348 LOC exceeds 3000 LOC limit

Fix: Decompose into smaller, focused modules

Functional Duplication Response Integration

Quality gates integrate with the Functional Duplication Prevention plan:

1. Automated Enforcement: Gates prevent new functional duplication
2. Business Logic Consolidation: Gates detect duplicate functions and traits
3. Interface Unification: Gates prevent duplicate trait definitions
4. Structural Cleanup: Gates allow language convention files while blocking problematic patterns

Monitoring & Artifacts

Generated Artifacts

Quality gates automatically create artifacts for monitoring and automation:

docs-status/
├── quality-gates-report.json    # Complete results (machine-readable)
└── refactoring-progress-report.json  # Refactoring metrics

JSON Report Structure

{
  "timestamp": "2025-10-28T22:01:19.090Z",
  "context": "commit|push|ci",
  "files_scoped": 13,
  "warnings": [
    {
      "gate": "naming|duplication|god_objects|documentation|code_freeze",
      "type": "violation_type",
      "message": "Human-readable description",
      "file": "relative/path/to/file",
      "severity": "warn"
    }
  ],
  "violations": [
    {
      "gate": "naming|duplication|god_objects|documentation|code_freeze",
      "type": "violation_type",
      "message": "Human-readable description",
      "file": "relative/path/to/file",
      "severity": "block|fail"
    }
  ]
}

Dashboard Integration

# Generate quality metrics for dashboards
node packages/quality-gates/run-quality-gates.mjs --json > quality-report.json

# Extract metrics for monitoring
jq '.violations | length' quality-report.json  # Total violations
jq '.warnings | length' quality-report.json    # Total warnings
jq '.files_scoped' quality-report.json         # Files analyzed

CI/CD Integration Examples

GitHub Actions

- name: Quality Gates
  run: node packages/quality-gates/run-quality-gates.mjs --ci --json > quality-report.json

- name: Upload Report
  uses: actions/upload-artifact@v3
  with:
    name: quality-gates-report
    path: quality-report.json

- name: Generate Summary
  run: GITHUB_STEP_SUMMARY=/tmp/summary.md node packages/quality-gates/run-quality-gates.mjs --ci

Jenkins Pipeline

stage('Quality Gates') {
    steps {
        sh 'node packages/quality-gates/run-quality-gates.mjs --ci --json > quality-report.json'
        archiveArtifacts artifacts: 'quality-report.json', fingerprint: true
    }
    post {
        always {
            sh 'cat quality-report.json | jq .violations'
        }
    }
}

Local Development Dashboard

# Run gates and generate local report
node packages/quality-gates/run-quality-gates.mjs --json > docs-status/quality-gates-report.json

# View violations by gate
jq '.violations | group_by(.gate) | map({gate: .[0].gate, count: length})' docs-status/quality-gates-report.json

Troubleshooting

Common Issues

Invalid Gate Names

# Error: Invalid gate names: invalid_gate
# Valid gates: naming, code_freeze, duplication, god_objects, documentation

# Fix: Use valid gate names
node packages/quality-gates/run-quality-gates.mjs --gates=naming,duplication

Documentation Linter Missing

# Error: Command failed: python3 "/Users/darianrosebrook/Desktop/Projects/caws/scripts/doc-quality-linter.py"

# Fix: Documentation quality gate requires Python script (currently missing)
# Skip documentation gate for now
node packages/quality-gates/run-quality-gates.mjs --gates=naming,code_freeze,duplication,god_objects

Context Determination Issues

# If context detection fails, gates fall back to 'commit' mode
# Override explicitly if needed
CAWS_ENFORCEMENT_CONTEXT=ci node packages/quality-gates/run-quality-gates.mjs

File Scoping Issues

# If files aren't being scoped correctly, check git status
git status --porcelain
# Ensure changes are staged for commit context

Performance Optimization

# Run gates in parallel (not yet implemented)
# For now, use selective gates for faster feedback
node packages/quality-gates/run-quality-gates.mjs --gates=naming  # Fast feedback
node packages/quality-gates/run-quality-gates.mjs --gates=duplication  # Slower

Debug Mode

# Enable verbose logging (if implemented)
DEBUG=quality-gates node packages/quality-gates/run-quality-gates.mjs

# Check individual gate outputs
node packages/quality-gates/check-naming.mjs
node packages/quality-gates/check-functional-duplication.mjs --context commit

Emergency Overrides

Exception-Based Overrides

Quality gates respect exceptions defined in .caws/quality-exceptions.json:

# View current exceptions
node packages/quality-gates/shared-exception-framework.mjs list

# Add temporary exception for specific file/pattern
node packages/quality-gates/shared-exception-framework.mjs add duplication \
  --pattern="src/temp-file.rs" \
  --reason="Temporary workaround for urgent fix" \
  --expires-days=7

Temporary Bypass (Not Recommended)

# Skip pre-commit hook (only for emergencies)
git commit --no-verify

# Skip specific gates in CI
node packages/quality-gates/run-quality-gates.mjs --gates=naming,god_objects  # Skip duplication

WARNING: Bypasses should only be used for critical hotfixes during crisis response.

Related Documentation

• Crisis Response Plan: docs/refactoring.md
• CAWS Integration: See CAWS documentation for workflow integration
• Exception Framework: packages/quality-gates/shared-exception-framework.mjs --help
• Refactoring Progress: packages/quality-gates/monitor-refactoring-progress.mjs

Audit Reports

• Naming Violations: docs/audits/v3-codebase-audit-2025-10/06-naming-violations.md
• Duplication Report: docs/audits/v3-codebase-audit-2025-10/02-duplication-report.md
• God Objects Analysis: docs/audits/v3-codebase-audit-2025-10/03-god-objects-analysis.md

Success Criteria

Quality gates are successful when they:

Core Quality Enforcement

• Block functional duplication increases (692+ struct, 200+ function, 100+ trait names)
• Prevent god object growth (no files >3K LOC, strict 2K LOC limits)
• Enforce code freeze compliance (block new features during freezes)
• Maintain architectural integrity (no naming violations, proper scoping)

Operational Excellence

• CI/CD integration works (JSON output, GitHub summaries, artifact generation)
• Exception framework functions (temporary waivers, audit trails, time-based expiry)
• Selective gate execution (targeted testing, faster feedback loops)
• Machine-readable outputs (JSON reports, dashboard integration)

Developer Experience

• Fast local feedback (gate filtering, clear error messages)
• Comprehensive monitoring (artifacts, metrics, trend analysis)
• Graceful error handling (fail-open for development, fail-closed for CI)
• Consistent reliability (consistent contexts, no emoji output)

Enterprise Integration

• CAWS workflow compatible (feature specs, progress tracking, provenance)
• Multi-environment support (commit/push/ci contexts, environment detection)
• Audit compliance ready (structured logs, violation tracking, exception management)
• Scalable architecture (concurrent processing ready, file scoping, performance monitoring)

Target: Configurable quality gates that prevent functional duplication while enabling controlled, monitored development workflows across all environments.