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:**

```typescript
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

- [x] Read ORCH-114 requirements
- [x] Review CoordinatorClientService interface
- [x] Design quality-gates.service.ts interface
- [x] Write tests (RED phase) - 22 comprehensive test cases
- [x] Implement service (GREEN phase) - All tests passing
- [x] Refactor and optimize (REFACTOR phase) - 91.66% branch coverage, 100% line coverage
- [x] Add service to CoordinatorModule
- [x] 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:

```typescript
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

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