# Human-in-the-Loop Gate Configuration Schema
# Based on REF-057 Agent Laboratory
# Finding: 84% cost reduction with HITL vs fully autonomous
# Issue: #96

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/hitl-gate/v1"
title: "HITL Gate Configuration Schema"
description: |
  Configurable human gates at phase transitions following Agent Laboratory patterns.
  Key insight: Draft-then-edit workflow achieves 84% cost reduction.

type: object
required:
  - id
  - name
  - gate_type
  - trigger
  - behavior

properties:
  $schema:
    type: string
    const: "https://aiwg.io/schemas/hitl-gate/v1"

  id:
    type: string
    pattern: "^GATE-[A-Z0-9]+(?:-[A-Z0-9]+)*$"
    maxLength: 100
    description: "Unique gate identifier; uppercase segments, e.g. GATE-C2I or GATE-AP-RECOVERY"

  name:
    type: string
    minLength: 5
    maxLength: 100
    description: "Human-readable gate name"

  description:
    type: string
    description: "Purpose and context for this gate"

  gate_type:
    type: string
    enum:
      - approval      # Requires explicit human approval to proceed
      - review        # Human reviews but auto-proceeds with timeout
      - escalation    # Triggered by specific conditions
      - checkpoint    # Informational, always proceeds
      - decision      # Human selects a disposition (e.g. false-positive override)
    description: "Type of human interaction required"

  trigger:
    type: object
    required: [type]
    description: "When this gate activates"
    properties:
      type:
        type: string
        enum:
          - phase_transition   # Between SDLC phases
          - artifact_complete  # When artifact is ready
          - threshold_breach   # When metric exceeds threshold
          - confidence_low     # When agent confidence is low
          - cost_threshold     # When cost exceeds budget
          - time_threshold     # After elapsed time
          - iteration_count    # After N iterations
          - error_pattern      # On specific error patterns
      description:
        type: string
      phase_from:
        type: string
        description: "Source phase (for phase_transition)"
      phase_to:
        type: string
        description: "Target phase (for phase_transition)"
      artifact_type:
        type: string
        description: "Artifact type (for artifact_complete)"
      threshold:
        type: number
        description: "Threshold value (for threshold triggers)"
      pattern:
        type: string
        description: "Pattern to match (for error_pattern)"

  behavior:
    type: object
    required: [mode, timeout_action]
    properties:
      mode:
        type: string
        enum:
          - ALWAYS      # Always require human input
          - NEVER       # Skip gate (for automation)
          - CONDITIONAL # Based on conditions
          - TERMINATE   # Stop execution at gate
        description: "Human input mode"

      timeout:
        type: integer
        minimum: 0
        description: "Timeout in seconds (0 = no timeout)"

      timeout_action:
        type: string
        enum:
          - proceed     # Continue after timeout
          - block       # Remain blocked
          - escalate    # Escalate to higher authority
          - abort       # Abort the operation
        description: "Action when timeout expires"

      auto_approve_conditions:
        type: array
        items:
          type: object
          properties:
            condition:
              type: string
              description: "Condition expression"
            reason:
              type: string
              description: "Why auto-approval is safe"
        description: "Conditions under which gate auto-approves"

      notification:
        type: object
        properties:
          channels:
            type: array
            items:
              type: string
              enum: [cli, issue_comment, slack, email]
          message_template:
            type: string
          urgency:
            type: string
            enum: [low, medium, high, critical]

  presentation:
    type: object
    description: "How to present gate to human"
    properties:
      summary_template:
        type: string
        description: "Template for gate summary"
      artifacts_to_show:
        type: array
        items:
          type: string
        description: "Artifact paths to display"
      questions:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            question:
              type: string
            options:
              type: array
              items:
                type: string
            required:
              type: boolean
        description: "Questions to ask human"
      context_window:
        type: integer
        description: "Lines of context to show"

  cost_tracking:
    type: object
    description: "Cost metrics for this gate"
    properties:
      track_enabled:
        type: boolean
        default: true
      metrics:
        type: array
        items:
          type: string
          enum:
            - time_to_decision
            - revision_count
            - token_cost_saved
            - error_prevented
            - destructive_action_rate
            - approval_rate
            - rejection_rate
            - alternative_found_rate
            - regret_rate
            - escalation_resolution_time
            - recovery_success_rate
            - false_positive_rate
            - detection_precision
            - whitelist_growth_rate
            - user_satisfaction
      baseline_comparison:
        type: string
        enum: [autonomous, previous_gate, manual]
        description: "What to compare cost savings against"

  audit:
    type: object
    description: "Audit trail requirements"
    properties:
      log_decision:
        type: boolean
        default: true
      log_rationale:
        type: boolean
        default: true
      require_signature:
        type: boolean
        default: false
      additional_fields:
        type: array
        items:
          type: string
      retention_days:
        type: integer
        default: 90

