# 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:
  id:
    type: string
    pattern: "^GATE-[A-Z0-9]{3,10}$"
    description: "Unique gate identifier"

  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
    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
      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
      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
      retention_days:
        type: integer
        default: 90

# Predefined gate templates
gate_templates:
  phase_approval:
    description: "Standard phase transition approval"
    gate_type: approval
    behavior:
      mode: CONDITIONAL
      timeout: 86400  # 24 hours
      timeout_action: block
      auto_approve_conditions:
        - condition: "confidence > 0.95 AND no_critical_issues"
          reason: "High confidence with no blockers"
    cost_tracking:
      track_enabled: true
      metrics: [time_to_decision, revision_count]

  artifact_review:
    description: "Artifact quality review"
    gate_type: review
    behavior:
      mode: ALWAYS
      timeout: 3600  # 1 hour
      timeout_action: proceed
    presentation:
      context_window: 100

  budget_checkpoint:
    description: "Cost threshold checkpoint"
    gate_type: escalation
    trigger:
      type: cost_threshold
    behavior:
      mode: CONDITIONAL
      timeout: 0
      timeout_action: abort

  iteration_checkpoint:
    description: "Progress checkpoint after iterations"
    gate_type: checkpoint
    trigger:
      type: iteration_count
      threshold: 5
    behavior:
      mode: CONDITIONAL
      timeout: 300
      timeout_action: proceed

# SDLC phase transition gates
sdlc_gates:
  concept_to_inception:
    id: "GATE-C2I"
    name: "Concept to Inception Gate"
    gate_type: approval
    trigger:
      type: phase_transition
      phase_from: concept
      phase_to: inception
    behavior:
      mode: ALWAYS
      timeout: 172800  # 48 hours
      timeout_action: block
    presentation:
      summary_template: |
        ## Ready for Inception?

        **Intake Form**: {{intake_status}}
        **Solution Profile**: {{solution_status}}
        **Stakeholders**: {{stakeholder_count}} identified

        Approve to begin formal requirements gathering.
      questions:
        - id: "scope_approved"
          question: "Is the project scope approved?"
          options: ["Yes", "No - needs refinement", "Escalate to sponsor"]
          required: true

  inception_to_elaboration:
    id: "GATE-I2E"
    name: "Inception to Elaboration Gate"
    gate_type: approval
    trigger:
      type: phase_transition
      phase_from: inception
      phase_to: elaboration
    behavior:
      mode: ALWAYS
      timeout: 172800
      timeout_action: block
    presentation:
      artifacts_to_show:
        - ".aiwg/requirements/user-stories.md"
        - ".aiwg/requirements/use-cases/"
        - ".aiwg/risks/risk-register.md"

  elaboration_to_construction:
    id: "GATE-E2C"
    name: "Elaboration to Construction Gate"
    gate_type: approval
    trigger:
      type: phase_transition
      phase_from: elaboration
      phase_to: construction
    behavior:
      mode: ALWAYS
      timeout: 172800
      timeout_action: block
    presentation:
      artifacts_to_show:
        - ".aiwg/architecture/software-architecture-doc.md"
        - ".aiwg/architecture/decisions/"
        - ".aiwg/testing/test-strategy.md"

  construction_to_transition:
    id: "GATE-C2T"
    name: "Construction to Transition Gate"
    gate_type: approval
    trigger:
      type: phase_transition
      phase_from: construction
      phase_to: transition
    behavior:
      mode: ALWAYS
      timeout: 86400
      timeout_action: block
    presentation:
      artifacts_to_show:
        - ".aiwg/testing/test-results/"
        - ".aiwg/deployment/deployment-plan.md"
        - ".aiwg/security/security-assessment.md"

# Cost savings tracking
cost_model:
  description: "Based on Agent Laboratory findings"
  baseline:
    fully_autonomous:
      average_cost_multiplier: 6.0
      error_rate: 0.35
      revision_cycles: 4.2
  with_hitl:
    average_cost_multiplier: 1.0
    error_rate: 0.05
    revision_cycles: 0.83
  savings_calculation: |
    savings = (autonomous_cost - hitl_cost) / autonomous_cost
    # Target: 84% cost reduction

# References
references:
  research:
    - "@.aiwg/research/findings/REF-057-agent-laboratory.md"
  implementation:
    - "#96"
  related:
    - "@agentic/code/frameworks/sdlc-complete/flows/"
    - "@agentic/code/frameworks/sdlc-complete/schemas/flows/"