Gates - Quality Validation (v2.37)

Comprehensive quality validation across 9 programming languages with TLDR-assisted analysis.

v2.88 Key Changes (MODEL-AGNOSTIC)

• Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
• No flags required: Works with the configured default model
• Flexible: Works with GLM-5, Claude, Minimax, or any configured model
• Settings-driven: Model selection via ANTHROPIC_DEFAULT_*_MODEL env vars

Quick Start

bash
1/gates              # Run all quality gates
2ralph gates         # Via CLI
3ralph gates src/    # Specific directory

LSP Usage for Type Checking

IMPORTANT: Use LSP for efficient type checking instead of reading entire files.

When to Use LSP

• Type checking TypeScript/JavaScript files
• Finding type errors without running tsc --noEmit
• Getting hover information for symbols
• Finding references across the codebase

LSP Commands

yaml
1# Type check a specific file (TypeScript)
2LSP:
3  server: typescript-language-server
4  action: diagnostics
5  file: src/auth/login.ts
6
7# Get hover information for a symbol
8LSP:
9  server: typescript-language-server
10  action: hover
11  file: src/auth/login.ts
12  line: 42
13  character: 10
14
15# Find all references
16LSP:
17  server: typescript-language-server
18  action: references
19  file: src/auth/login.ts
20  line: 42
21  character: 10
22
23# Python type checking with pyright
24LSP:
25  server: pyright
26  action: diagnostics
27  file: src/auth/login.py

LSP vs Traditional Type Checking

Pre-Gates: TLDR Language Detection (v2.37)

AUTOMATIC - Detect project languages efficiently:

bash
1# Get codebase structure to detect languages (95% token savings)
2tldr structure . > /tmp/project-structure.md
3
4# From structure, identify:
5# - Primary language(s)
6# - Config files present
7# - Test frameworks used

Supported Languages

Workflow

1. Detect Languages

bash
1# Auto-detect based on file extensions and config files

2. Run Linters

bash
1# Per-language linting
2npx eslint src/          # TypeScript/JavaScript
3ruff check .             # Python
4cargo clippy             # Rust
5golangci-lint run        # Go

3. Check Formatting

bash
1npx prettier --check .   # JS/TS
2black --check .          # Python
3rustfmt --check src/     # Rust
4gofmt -l .               # Go

4. Type Checking

bash
1npx tsc --noEmit         # TypeScript
2mypy .                   # Python
3cargo check              # Rust
4go vet ./...             # Go

5. Run Tests

bash
1npm test                 # Node projects
2pytest                   # Python
3cargo test               # Rust
4go test ./...            # Go

Exit Codes

Gate Configuration

Minimal (fast)

bash
1ralph gates --minimal    # Lint only

Standard (default)

bash
1ralph gates              # Lint + Format + Types

Full (CI)

bash
1ralph gates --full       # Lint + Format + Types + Tests

Integration

• Invoked by /orchestrator in Step 6
• Pre-step: tldr structure for language detection (v2.37)
• Must pass before VERIFIED_DONE
• Hooks: quality-gates.sh (PostToolUse)

TLDR Integration (v2.37)

Agent Teams Integration (v2.88)

Optimal Scenario: Integrated (Agent Teams + Custom Subagents)

Quality gates use Agent Teams coordination with specialized ralph-tester agents for parallel quality validation.

Why Scenario C for Gates

• Multiple quality checks require coordination (lint, format, type, test)
• Quality gates are meta-validation (hooks validate the validators)
• Language-specific specialization via ralph-tester
• TeammateIdle/TaskCompleted hooks for quality enforcement

Subagent Roles

Parallel Gates Execution

When Agent Teams is active, gates run in parallel across subagents:

1. Team Lead creates task list with gate phases
2. ralph-tester runs tests concurrently
3. ralph-reviewer reviews linter output
4. ralph-coder applies fixes

Quality Gate Hooks

• TeammateIdle: Triggers before agent goes idle
• TaskCompleted: Validates gate completion

Action Reporting (v2.93.0)

Los resultados de /gates generan reportes automáticos completos:

Reporte Automático

Cuando /gates completa, se genera automáticamente:

1. En la conversación de Claude: Resultados visibles de todas las validaciones
2. En el repositorio: docs/actions/gates/{timestamp}.md
3. Metadatos JSON: .claude/metadata/actions/gates/{timestamp}.json

Contenido del Reporte

Cada reporte incluye:

• ✅ Summary: Tipo de validación ejecutada
• ✅ Results: Resultados de linters, formatters, type checkers, tests
• ✅ Errors: Errores encontrados por categoría
• ✅ Recommendations: Acciones correctivas sugeridas
• ✅ Next Steps: Qué hacer según el resultado

Generación Manual (Opcional)

bash
1# Al inicio
2source .claude/lib/action-report-lib.sh
3start_action_report "gates" "Running quality gates on src/"
4
5# Ejecutar validaciones
6if ! npx tsc --noEmit; then
7    record_error "TypeScript errors found"
8fi
9
10if ! npx eslint .; then
11    record_error "ESLint violations found"
12fi
13
14if ! npm test; then
15    record_error "Test failures found"
16fi
17
18# Al completar
19if [[ ${#CURRENT_ACTION_ERRORS[@]} -eq 0 ]]; then
20    complete_action_report \
21        "success" \
22        "All quality gates passed" \
23        "Safe to commit: git commit -m 'chore: pass quality gates'"
24else
25    complete_action_report \
26        "failed" \
27        "Quality gates failed" \
28        "Fix errors and run /gates again"
29fi

Ver Reportes Anteriores

bash
1# Listar todos los reportes de gates
2ls -lt docs/actions/gates/
3
4# Ver el reporte más reciente
5cat $(ls -t docs/actions/gates/*.md | head -1)
6
7# Buscar reportes fallidos
8grep -l "Status: FAILED" docs/actions/gates/*.md
9
10# Ver tendencia de calidad
11grep -c "Status: COMPLETED" docs/actions/gates/*.md
12grep -c "Status: FAILED" docs/actions/gates/*.md

Integración CI/CD

Los metadatos JSON permiten integración con pipelines:

bash
1# En tu CI pipeline
2source .claude/lib/action-report-generator.sh
3
4# Ejecutar gates
5/gates
6
7# Obtener resultado del último reporte
8latest_report=$(find_latest_report "gates")
9status=$(grep "Status:" "$latest_report" | awk '{print $2}')
10
11if [[ "$status" != "COMPLETED" ]]; then
12    echo "Quality gates failed - blocking commit"
13    exit 1
14fi

Referencias del Sistema de Reportes

• Action Reports System - Documentación completa
• action-report-lib.sh - Librería helper
• action-report-generator.sh - Generador

Anti-Patterns

• Never skip gates for "quick fixes"
• Never ignore type errors
• Never commit with lint warnings