stack/docs/scratchpads/orch-123-yolo.md

# Issue ORCH-123: YOLO mode (gate bypass)

## Objective

Implement user-configurable approval gates with YOLO mode that bypasses quality gates.

## Acceptance Criteria

- [ ] Configuration option: `YOLO_MODE=true`
- [ ] If YOLO mode enabled, skip quality gates
- [ ] Log YOLO mode usage (audit trail)
- [ ] UI warning: "Quality gates disabled" (return in API responses)

## Approach

### 1. Configuration

- Add `YOLO_MODE` environment variable to orchestrator.config.ts
- Default: false (quality gates enabled)

### 2. QualityGatesService

- Check YOLO_MODE before running gates
- If YOLO enabled:
  - Skip coordinator API calls
  - Log YOLO usage with audit trail
  - Return approved result with warning message
- If YOLO disabled:
  - Run gates normally

### 3. Testing (TDD)

- Write tests FIRST
- Test YOLO enabled scenario (gates skipped)
- Test YOLO disabled scenario (gates run normally)
- Test logging of YOLO usage
- Ensure test coverage >= 85%

## Progress

- [x] Read issue requirements
- [x] Create scratchpad
- [x] Write failing tests for YOLO mode (RED phase)
- [x] Add YOLO_MODE to config
- [x] Implement YOLO mode in QualityGatesService (GREEN phase)
- [x] All tests pass (47/47 passing)
- [x] Add YOLO_MODE to .env.example
- [x] Verify test coverage >= 85% (100% statements, 95.23% branches)
- [x] Create Gitea issue #258
- [x] Close Gitea issue #258 with completion notes

## COMPLETED ✅

## Testing

### Test Cases

1. **YOLO mode enabled - pre-commit check**
   - Given: YOLO_MODE=true
   - When: preCommitCheck() called
   - Then: Gates skipped, approved=true, warning message returned, YOLO usage logged

2. **YOLO mode enabled - post-commit check**
   - Given: YOLO_MODE=true
   - When: postCommitCheck() called
   - Then: Gates skipped, approved=true, warning message returned, YOLO usage logged

3. **YOLO mode disabled - pre-commit check**
   - Given: YOLO_MODE=false
   - When: preCommitCheck() called
   - Then: Gates run normally via coordinator

4. **YOLO mode disabled - post-commit check**
   - Given: YOLO_MODE=false
   - When: postCommitCheck() called
   - Then: Gates run normally via coordinator

5. **YOLO mode not set (default)**
   - Given: YOLO_MODE not set
   - When: preCommitCheck() called
   - Then: Gates run normally (default = false)

## Notes

- YOLO mode is opt-in for development/testing scenarios
- Default behavior: quality gates enabled
- Audit logging is critical for compliance
- Warning message helps UI communicate risk to users

## Implementation Details

### Configuration Changes

- Added `yolo.enabled` to `orchestrator.config.ts`
- Reads from `YOLO_MODE` environment variable
- Default value: `false` (ensures safety by default)

### Service Changes

- Added `ConfigService` dependency to `QualityGatesService`
- Added `isYoloModeEnabled()` private method to check configuration
- Added `bypassQualityGates()` private method that:
  - Logs complete audit trail with warn level
  - Returns approved result with warning message
  - Includes YOLO mode flag in response details
- Modified `preCommitCheck()` to check YOLO mode first
- Modified `postCommitCheck()` to check YOLO mode first

### Audit Trail Format

```typescript
{
  taskId: string,
  agentId: string,
  gate: 'pre-commit' | 'post-commit',
  files: string[],
  timestamp: ISO 8601 string
}
```

### Response Format (YOLO enabled)

```typescript
{
  approved: true,
  gate: 'pre-commit' | 'post-commit',
  message: 'Quality gates disabled (YOLO mode)',
  details: {
    yoloMode: true,
    warning: 'Quality gates were bypassed. Code may not meet quality standards.'
  }
}
```

## Test Coverage

- Total tests: 47 (10 new YOLO tests + 37 existing tests)
- Statement coverage: 100%
- Branch coverage: 95.23%
- Function coverage: 100%
- Line coverage: 100%

## Gitea Issue

- Issue #258: https://git.mosaicstack.dev/mosaic/stack/issues/258
- Status: Closed
- Created and closed: 2026-02-02