stack/docs/scratchpads/orch-114-gates.md

Issue ORCH-114: Quality Gate Callbacks

Objective

Implement quality gate callbacks that call coordinator quality gates before commit/push.

Approach

Following TDD principles:

1. RED: Write tests first for quality-gates.service.ts
2. GREEN: Implement minimal code to pass tests
3. REFACTOR: Clean up and optimize

Key Requirements (from M6-NEW-ISSUES-TEMPLATES.md)

• src/coordinator/quality-gates.service.ts implemented
• Pre-commit quality check (before git commit)
• Post-commit quality check (before git push)
• Parse quality gate response
• Block commit/push if rejected
• Return rejection details to agent

Design

Service Interface:

class QualityGatesService {
  constructor(coordinatorClient: CoordinatorClientService) {}

  // Pre-commit: runs before git commit
  async preCommitCheck(params: PreCommitCheckParams): Promise<QualityGateResult>;

  // Post-commit: runs before git push
  async postCommitCheck(params: PostCommitCheckParams): Promise<QualityGateResult>;
}

Quality Gate Types:

• Pre-commit: typecheck, lint, tests
• Post-commit: coverage, build, integration tests

Integration:

• Use CoordinatorClientService.checkQuality()
• Parse response (approved/rejected)
• Return detailed rejection info to caller

Progress

• Read ORCH-114 requirements
• Review CoordinatorClientService interface
• Design quality-gates.service.ts interface
• Write tests (RED phase) - 22 comprehensive test cases
• Implement service (GREEN phase) - All tests passing
• Refactor and optimize (REFACTOR phase) - 91.66% branch coverage, 100% line coverage
• Add service to CoordinatorModule
• Create/close Gitea issue - Issue #249 created and closed

Testing Strategy

Test Scenarios

1. Pre-commit approved: All gates pass
2. Pre-commit rejected: Lint fails
3. Post-commit approved: All gates pass
4. Post-commit rejected: Coverage insufficient
5. Coordinator unavailable: Service retries
6. Invalid response: Error handling
7. Multiple file changes: Diff summary handling

Mock Strategy

• Mock CoordinatorClientService
• Test both approval and rejection flows
• Test error propagation
• Verify proper gate type selection

Notes

CoordinatorClientService Interface

From orch-113-coordinator.md and coordinator-client.service.ts:

interface QualityCheckRequest {
  taskId: string;
  agentId: string;
  files: string[];
  diffSummary: string;
}

interface QualityCheckResponse {
  approved: boolean;
  gate: string;
  message?: string;
  details?: Record<string, unknown>;
}

class CoordinatorClientService {
  async checkQuality(request: QualityCheckRequest): Promise<QualityCheckResponse>;
  async isHealthy(): Promise<boolean>;
}

Quality Gate Phases

Pre-commit (before git commit):

• Runs fast gates: typecheck, lint, unit tests
• Blocks commit if any fail
• Returns detailed errors for agent to fix

Post-commit (before git push):

• Runs comprehensive gates: coverage, build, integration tests
• Blocks push if any fail
• Can include AI reviewer confirmation

Blockers

None - ORCH-113 is complete and available.

Related Issues

• ORCH-113: Coordinator API client (complete)
• ORCH-121: Mechanical quality gates (coordinator implementation)
• ORCH-116: 50% rule enforcement

Implementation Summary

Files Created

1. src/coordinator/quality-gates.service.ts (161 lines)

   • QualityGatesService class with NestJS dependency injection
   • Pre-commit check method (typecheck, lint, tests)
   • Post-commit check method (coverage, build, integration tests)
   • Comprehensive logging and error handling

2. src/coordinator/quality-gates.service.spec.ts (22 test cases)

   • Pre-commit approval/rejection scenarios
   • Post-commit approval/rejection scenarios
   • Error handling (coordinator unavailable, network errors, timeouts)
   • Response parsing and validation
   • Multiple file changes handling
   • Non-Error exception handling

Test Coverage

• Statements: 100%
• Branches: 91.66% (exceeds 85% requirement)
• Functions: 100%
• Lines: 100%

Module Integration

Updated coordinator.module.ts to export QualityGatesService alongside CoordinatorClientService.

Key Features

1. Pre-commit gates: Fast checks before commit

   • Type checking
   • Linting
   • Unit tests
   • Blocks commit if any fail

2. Post-commit gates: Comprehensive checks before push

   • Code coverage (>= 85%)
   • Build verification
   • Integration tests
   • AI reviewer confirmation (optional)
   • Blocks push if any fail

3. Error handling: Robust retry logic

   • Propagates coordinator client errors
   • Handles network failures
   • Timeout handling
   • Non-Error exception handling

4. Response parsing: Type-safe response mapping

   • Preserves all coordinator response fields
   • Returns detailed rejection info
   • Includes gate-specific details for debugging

Acceptance Criteria - COMPLETED

• src/coordinator/quality-gates.service.ts implemented
• Pre-commit quality check (before git commit)
• Post-commit quality check (before git push)
• Parse quality gate response
• Block commit/push if rejected
• Return rejection details to agent
• Comprehensive unit tests (22 test cases)
• Test coverage >= 85% (achieved 91.66% branch, 100% line)
• NestJS service with proper dependency injection
• Integration with CoordinatorClientService