stack/docs/scratchpads/orch-124-task-config.md

Issue ORCH-124: Gate configuration per-task

Objective

Implement per-task quality gate configuration allowing different quality gates for different task types. Different requirements for worker, reviewer, and tester agents with configurable gate thresholds per task type.

Approach

1. Define Gate Profile Types

• Strict Profile: All gates (typecheck, lint, tests, coverage, build, integration, AI review)
• Standard Profile: tests + lint + typecheck + coverage
• Minimal Profile: tests only
• Custom Profile: User-defined gate selection

2. Configuration Structure

interface GateProfile {
  name: "strict" | "standard" | "minimal" | "custom";
  gates: {
    typecheck?: boolean;
    lint?: boolean;
    tests?: boolean;
    coverage?: { enabled: boolean; threshold?: number };
    build?: boolean;
    integration?: boolean;
    aiReview?: boolean;
  };
}

interface TaskGateConfig {
  taskId: string;
  agentType: "worker" | "reviewer" | "tester";
  profile: GateProfile;
}

3. Implementation Plan

Phase 1: Types and Interfaces

• Create gate profile types
• Create task gate configuration interface
• Define default profiles

Phase 2: Gate Configuration Service

• Service to manage gate configurations
• Get configuration for task
• Validate gate configuration
• Apply profile to task

Phase 3: Integration with Quality Gates Service

• Update QualityGatesService to use task configuration
• Pass gate requirements to coordinator
• Filter gates based on configuration

Phase 4: API Integration

• Add gateConfig to SpawnAgentDto
• Store gate configuration with task metadata
• Retrieve configuration during quality checks

Progress

• Create scratchpad
• Define types and interfaces
• Write tests for GateConfigService (TDD - RED phase)
• Implement GateConfigService (TDD - GREEN phase)
• Integrate with QualityGatesService
• Update SpawnAgentDto
• All tests passing
• Coverage >= 85%

Testing

Unit Tests

1. ✅ GateConfigService tests

   • Get default configuration for agent types
   • Apply profile to task
   • Validate gate configuration
   • Custom gate configuration
   • Invalid profile handling

2. ✅ QualityGatesService integration tests

   • Use task-specific gate configuration
   • Skip gates not in configuration
   • Apply coverage threshold from config
   • YOLO mode overrides gate config

Test Coverage

• Target: >= 85%
• Actual: Will verify after implementation

Notes

Design Decisions

1. Profile-Based Configuration: Use predefined profiles (strict, standard, minimal) for ease of use, with custom option for flexibility.

2. Default Behavior:

   • Worker agents: Standard profile (tests + lint + typecheck + coverage)
   • Reviewer agents: Strict profile (all gates including AI review)
   • Tester agents: Minimal profile (tests only)

3. Gate Selection: Configuration specifies which gates to run, not which to skip. This is more explicit and safer.

4. Coverage Threshold: Can be customized per task (default 85%).

5. Integration Pattern: GateConfigService provides configuration, QualityGatesService enforces it by passing requirements to coordinator.

Implementation Notes

• Gate configuration is immutable once task is created (stored with task metadata)
• YOLO mode bypasses all gate configurations
• Invalid configurations fall back to safe defaults
• Configuration validation happens at spawn time, not at check time
• Coordinator receives gate requirements and runs only requested gates

Examples

Strict Profile (All Gates):

{
  profile: 'strict',
  gates: {
    typecheck: true,
    lint: true,
    tests: true,
    coverage: { enabled: true, threshold: 85 },
    build: true,
    integration: true,
    aiReview: true
  }
}

Standard Profile (Core Gates):

{
  profile: 'standard',
  gates: {
    typecheck: true,
    lint: true,
    tests: true,
    coverage: { enabled: true, threshold: 85 }
  }
}

Minimal Profile (Tests Only):

{
  profile: 'minimal',
  gates: {
    tests: true
  }
}

Custom Profile (Docs Task):

{
  profile: 'custom',
  gates: {
    lint: true,
    tests: false, // No tests required for docs
    coverage: { enabled: false }
  }
}

Completion Criteria

• Types defined for gate profiles and configurations
• GateConfigService implemented with default profiles
• QualityGatesService updated to use gate configuration
• SpawnAgentDto extended with optional gateConfig
• Unit tests written and passing (TDD)
• Test coverage >= 85% (Achieved: 98.3% for coordinator module)
• Create Gitea issue
• Close issue with completion notes

Final Results

Test Results

• GateConfigService: 35 tests, all passing
• QualityGatesService: 54 tests, all passing (including 7 new gate config tests)
• Overall Coverage: 93.58% (coordinator module: 98.3%)

Files Created/Modified

1. Created: src/coordinator/types/gate-config.types.ts - Type definitions
2. Created: src/coordinator/gate-config.service.ts - Service implementation
3. Created: src/coordinator/gate-config.service.spec.ts - Unit tests
4. Created: src/coordinator/types/index.ts - Type exports
5. Modified: src/coordinator/quality-gates.service.ts - Integration with gate config
6. Modified: src/coordinator/quality-gates.service.spec.ts - Added integration tests
7. Modified: src/coordinator/coordinator-client.service.ts - Added gateRequirements to request
8. Modified: src/api/agents/dto/spawn-agent.dto.ts - Added gateProfile field

Features Implemented

1. ✅ Four gate profiles: strict, standard, minimal, custom
2. ✅ Default profiles per agent type (reviewer=strict, worker=standard, tester=minimal)
3. ✅ Custom gate selection with validation
4. ✅ Custom coverage thresholds per task
5. ✅ Backward compatibility (works without gate config)
6. ✅ YOLO mode overrides gate config
7. ✅ Profile metadata tracking
8. ✅ Gate requirements passed to coordinator

Usage Examples

Spawn worker with default (standard) profile:

{
  taskId: "task-123",
  agentType: "worker"
  // Uses standard profile automatically
}

Spawn worker with custom profile:

{
  taskId: "task-123",
  agentType: "worker",
  gateProfile: "minimal" // Override to minimal
}

Docs task with custom gates:

{
  taskId: "task-docs-001",
  agentType: "worker",
  gateProfile: "custom",
  customGates: {
    lint: true // Only lint for docs
  }
}