workflow_record_schema.yaml

# Copyright 2025-2026 GitGovernance (https://www.gitgovernance.com)
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# ---
# WorkflowRecord Schema (v1.0)
# Part of the GitGovernance Protocol — designed and maintained by GitGovernance.
# Specification: RFC-08 (08_workflow.md)

$schema: "http://json-schema.org/draft-07/schema#"
$id: "workflow_record_schema.yaml"
title: "WorkflowRecord"
description: "Schema for workflow methodology configuration that defines named state transitions, signatures, and custom rules."
type: object
required:
  - id
  - name
  - state_transitions
additionalProperties: false

properties:
  id:
    type: string
    pattern: "^\\d{10}-workflow-[a-z0-9-]{1,50}$"
    maxLength: 70
    description: "Unique identifier for the workflow record (10 timestamp + 1 dash + 8 'workflow' + 1 dash + max 50 slug = 70 max)"

  name:
    type: string
    minLength: 1
    maxLength: 100
    description: "Human-readable name of the methodology"

  description:
    type: string
    maxLength: 500
    description: "Brief description of the methodology's purpose and scope"

  state_transitions:
    type: object
    description: "Map of named transitions to their rules. Keys are transition names (e.g., submit, approve, activate, resume), not target states."
    propertyNames:
      pattern: "^[a-z][a-z0-9_]{0,49}$"
    additionalProperties:
      type: object
      required:
        - from
        - to
        - requires
      additionalProperties: false
      properties:
        from:
          type: array
          items:
            type: string
            pattern: "^[a-z][a-z0-9_]{0,49}$"
          minItems: 1
          description: "Valid source states for this transition"

        to:
          type: string
          pattern: "^[a-z][a-z0-9_]{0,49}$"
          description: "Target state for this transition"

        requires:
          type: object
          additionalProperties: false
          properties:
            command:
              type: string
              description: "CLI command that triggers this transition (Command Gate)"

            event:
              type: string
              description: "System event that triggers this transition (Event Gate)"

            signatures:
              type: object
              description: "Signature group requirements (Signature Gate)"
              additionalProperties:
                type: object
                required:
                  - role
                  - capability_roles
                  - min_approvals
                additionalProperties: false
                properties:
                  role:
                    type: string
                    description: "Required signature role"

                  capability_roles:
                    type: array
                    items:
                      type: string
                    minItems: 1
                    description: "Required capability roles in actor record"

                  min_approvals:
                    type: integer
                    minimum: 1
                    description: "Minimum number of required approvals"

                  actor_type:
                    type: string
                    enum: ["human", "agent"]
                    description: "Optional: restrict to specific actor type"

                  specific_actors:
                    type: array
                    items:
                      type: string
                    description: "Optional: restrict to specific actor IDs"

            custom_rules:
              type: array
              items:
                type: string
              description: "List of custom rule identifiers to validate"

  custom_rules:
    type: object
    description: "Definitions for custom validation rules"
    additionalProperties:
      type: object
      required:
        - description
        - validation
      additionalProperties: false
      properties:
        description:
          type: string
          maxLength: 200
          description: "Human-readable description of the rule"

        validation:
          type: string
          enum:
            - "assignment_required"
            - "sprint_capacity"
            - "epic_complexity"
            - "custom"
          description: "Validation type identifier"

        parameters:
          type: object
          description: "Optional parameters for the validation rule"

        expression:
          type: string
          description: "Inline validation expression for 'custom' type. Must return boolean."

        module_path:
          type: string
          description: "Path to external module for custom validation (alternative to expression)"

  agent_integration:
    type: object
    description: "Optional agent automation configuration"
    additionalProperties: false
    properties:
      description:
        type: string
        maxLength: 200
        description: "Brief description of the agent integration"

      required_agents:
        type: array
        description: "Agents required for this methodology"
        items:
          type: object
          required:
            - triggers
          anyOf:
            - required: [id]
            - required: [required_roles]
          additionalProperties: false
          properties:
            id:
              type: string
              pattern: "^agent(:[a-z0-9-]+)+$"
              description: "Specific agent ID (references an AgentRecord)"

            required_roles:
              type: array
              items:
                type: string
                pattern: "^[a-z0-9-]+(:[a-z0-9-]+)*$"
              minItems: 1
              description: "Required capability roles (matches any agent with these roles)"

            triggers:
              type: array
              description: "Events that activate this agent"
              items:
                type: object
                required:
                  - event
                  - action
                additionalProperties: false
                properties:
                  event:
                    type: string
                    description: "Event that triggers the agent"
                  action:
                    type: string
                    description: "Action the agent should perform"
                  cron:
                    type: string
                    description: "Cron expression for scheduled triggers"