aiox-core 5.0.4 → 5.0.7

package/pro/squads/aiox-sop/data/sop-ml-schema.yaml

@@ -0,0 +1,780 @@
+# =============================================================================
+# SOP ML Schema - Machine-Readable SOP Contract
+# =============================================================================
+# Used by: sop-ml-architect (create-sop-ml task), sop-auditor (ML validation)
+# Version: 1.0.0
+#
+# Purpose:
+#   Defines the formal schema for AI/ML-readable SOPs. Any ML SOP produced
+#   by the SOP Factory must conform to this schema. This enables:
+#   - Automated SOP execution by AI agents
+#   - Programmatic validation and auditing
+#   - Integration with workflow orchestration systems
+#   - Machine-to-machine SOP exchange
+#   - Automated compliance checking
+#
+# Schema Notation:
+#   required: true/false   - Whether the field must be present
+#   type: string/number/boolean/array/object/enum
+#   enum_values: [...]     - Valid values for enum fields
+#   constraints: ...       - Additional validation rules
+# =============================================================================
+
+schema:
+  version: "1.0.0"
+  schema_id: "sop-ml-schema-v1"
+  format: "YAML"
+  media_type: "application/x-sop-ml+yaml"
+
+  # ===========================================================================
+  # ROOT STRUCTURE
+  # ===========================================================================
+  root:
+    type: object
+    required_fields:
+      - sop_ml
+    description: "Root element of an ML-readable SOP document"
+
+  # ===========================================================================
+  # SOP_ML - Top-level container
+  # ===========================================================================
+  fields:
+
+    sop_ml:
+      type: object
+      required: true
+      description: "Top-level container for the machine-readable SOP"
+      children:
+
+        # --- METADATA SECTION ---
+        metadata:
+          type: object
+          required: true
+          description: "Document identification and control information"
+          children:
+
+            schema_version:
+              type: string
+              required: true
+              description: "Version of sop-ml-schema this document conforms to"
+              constraints:
+                pattern: "^\\d+\\.\\d+\\.\\d+$"
+              example: "1.0.0"
+
+            sop_id:
+              type: string
+              required: true
+              description: "Unique identifier for this SOP"
+              constraints:
+                pattern: "^SOP-[A-Z]+-\\d{3,}$"
+                unique: true
+              example: "SOP-DEV-001"
+
+            title:
+              type: string
+              required: true
+              description: "Human-readable title of the SOP"
+              constraints:
+                max_length: 200
+              example: "Database Backup and Recovery Procedure"
+
+            version:
+              type: string
+              required: true
+              description: "Semantic version of this SOP"
+              constraints:
+                pattern: "^\\d+\\.\\d+\\.\\d+$"
+              example: "1.2.0"
+
+            status:
+              type: enum
+              required: true
+              description: "Current lifecycle status"
+              enum_values:
+                - draft
+                - review
+                - approved
+                - published
+                - deprecated
+                - archived
+
+            created_date:
+              type: string
+              required: true
+              description: "ISO 8601 date of initial creation"
+              constraints:
+                format: "date"  # YYYY-MM-DD
+              example: "2026-03-09"
+
+            last_updated:
+              type: string
+              required: true
+              description: "ISO 8601 date of last modification"
+              constraints:
+                format: "date"
+              example: "2026-03-09"
+
+            next_review:
+              type: string
+              required: false
+              description: "ISO 8601 date of next scheduled review"
+              constraints:
+                format: "date"
+
+            owner:
+              type: object
+              required: true
+              description: "Person or role accountable for this SOP"
+              children:
+                role:
+                  type: string
+                  required: true
+                  example: "DevOps Lead"
+                name:
+                  type: string
+                  required: false
+                  example: "Jane Smith"
+                contact:
+                  type: string
+                  required: false
+                  example: "devops-lead@company.com"
+
+            tags:
+              type: array
+              required: false
+              description: "Searchable tags for categorization"
+              items:
+                type: string
+              example: ["database", "backup", "disaster-recovery", "infrastructure"]
+
+            compliance:
+              type: array
+              required: false
+              description: "Applicable compliance standards"
+              items:
+                type: object
+                children:
+                  standard_id:
+                    type: string
+                    required: true
+                    example: "ISO-9001"
+                  clauses:
+                    type: array
+                    required: false
+                    items:
+                      type: string
+                    example: ["7.5", "8.1"]
+
+            source:
+              type: object
+              required: false
+              description: "Provenance information if extracted from another source"
+              children:
+                type:
+                  type: enum
+                  required: true
+                  enum_values:
+                    - original
+                    - extracted
+                    - converted
+                    - merged
+                source_ref:
+                  type: string
+                  required: false
+                  description: "Reference to original source"
+                extraction_confidence:
+                  type: number
+                  required: false
+                  constraints:
+                    min: 0.0
+                    max: 1.0
+
+        # --- PURPOSE SECTION ---
+        purpose:
+          type: object
+          required: true
+          description: "Why this SOP exists and what it covers"
+          children:
+
+            objective:
+              type: string
+              required: true
+              description: "Clear statement of what this SOP achieves"
+              example: "Ensure consistent, reliable database backup and recovery across all production environments."
+
+            scope:
+              type: object
+              required: true
+              children:
+                in_scope:
+                  type: array
+                  required: true
+                  items:
+                    type: string
+                  example:
+                    - "Production PostgreSQL databases"
+                    - "Staging PostgreSQL databases"
+                out_of_scope:
+                  type: array
+                  required: false
+                  items:
+                    type: string
+                  example:
+                    - "Development/local databases"
+                    - "Third-party SaaS data"
+
+            target_audience:
+              type: array
+              required: true
+              description: "Who or what executes this SOP"
+              items:
+                type: object
+                children:
+                  type:
+                    type: enum
+                    required: true
+                    enum_values:
+                      - human
+                      - ai_agent
+                      - automated_system
+                      - hybrid
+                  role:
+                    type: string
+                    required: true
+                    example: "Database Administrator"
+                  required_skills:
+                    type: array
+                    required: false
+                    items:
+                      type: string
+
+        # --- DEFINITIONS SECTION ---
+        definitions:
+          type: array
+          required: false
+          description: "Glossary of terms used in this SOP"
+          items:
+            type: object
+            children:
+              term:
+                type: string
+                required: true
+              definition:
+                type: string
+                required: true
+              acronym:
+                type: string
+                required: false
+
+        # --- RACI SECTION ---
+        raci:
+          type: array
+          required: true
+          description: "RACI matrix mapping activities to roles"
+          items:
+            type: object
+            children:
+              activity:
+                type: string
+                required: true
+                description: "The activity or step group"
+              responsible:
+                type: string
+                required: true
+                description: "Role that executes"
+              accountable:
+                type: string
+                required: true
+                description: "Role ultimately answerable"
+              consulted:
+                type: array
+                required: false
+                items:
+                  type: string
+                description: "Roles providing input"
+              informed:
+                type: array
+                required: false
+                items:
+                  type: string
+                description: "Roles notified of outcome"
+
+        # --- PREREQUISITES SECTION ---
+        prerequisites:
+          type: object
+          required: true
+          description: "Everything needed before execution can begin"
+          children:
+
+            tools:
+              type: array
+              required: false
+              description: "Software, hardware, or physical tools required"
+              items:
+                type: object
+                children:
+                  name:
+                    type: string
+                    required: true
+                  version:
+                    type: string
+                    required: false
+                  purpose:
+                    type: string
+                    required: false
+                  install_command:
+                    type: string
+                    required: false
+                    description: "Command to install/verify the tool (for AI agents)"
+
+            access:
+              type: array
+              required: false
+              description: "Permissions and access required"
+              items:
+                type: object
+                children:
+                  system:
+                    type: string
+                    required: true
+                  level:
+                    type: string
+                    required: true
+                    example: "admin"
+                  how_to_request:
+                    type: string
+                    required: false
+
+            conditions:
+              type: array
+              required: false
+              description: "Environmental or state conditions that must be true"
+              items:
+                type: object
+                children:
+                  condition:
+                    type: string
+                    required: true
+                  verification:
+                    type: string
+                    required: false
+                    description: "Command or check to verify the condition"
+
+        # --- PROCEDURE SECTION ---
+        procedure:
+          type: object
+          required: true
+          description: "The core procedural steps"
+          children:
+
+            phases:
+              type: array
+              required: true
+              description: "Ordered list of phases, each containing steps"
+              items:
+                type: object
+                children:
+
+                  phase_id:
+                    type: string
+                    required: true
+                    constraints:
+                      pattern: "^P\\d{1,3}$"
+                    example: "P1"
+
+                  name:
+                    type: string
+                    required: true
+
+                  description:
+                    type: string
+                    required: false
+
+                  estimated_duration:
+                    type: string
+                    required: false
+                    description: "ISO 8601 duration or human-readable estimate"
+                    example: "PT15M"
+
+                  steps:
+                    type: array
+                    required: true
+                    items:
+                      type: object
+                      children:
+
+                        step_id:
+                          type: string
+                          required: true
+                          constraints:
+                            pattern: "^S\\d{1,3}\\.\\d{1,3}$"
+                          example: "S1.1"
+
+                        action:
+                          type: string
+                          required: true
+                          description: "The action to perform (starts with verb)"
+                          constraints:
+                            starts_with_verb: true
+
+                        actor:
+                          type: string
+                          required: true
+                          description: "Role or system performing this step"
+
+                        input:
+                          type: object
+                          required: false
+                          description: "Input data or artifacts needed"
+                          children:
+                            type:
+                              type: enum
+                              required: true
+                              enum_values:
+                                - user_input
+                                - system_data
+                                - file
+                                - api_response
+                                - previous_step_output
+                                - environment_variable
+                                - constant
+                            source:
+                              type: string
+                              required: false
+                            format:
+                              type: string
+                              required: false
+
+                        output:
+                          type: object
+                          required: false
+                          description: "Expected output or artifact produced"
+                          children:
+                            type:
+                              type: enum
+                              required: true
+                              enum_values:
+                                - file
+                                - log_entry
+                                - state_change
+                                - notification
+                                - api_call
+                                - data_record
+                                - report
+                                - none
+                            description:
+                              type: string
+                              required: false
+                            location:
+                              type: string
+                              required: false
+
+                        command:
+                          type: string
+                          required: false
+                          description: "Exact command to execute (for AI agents/automation)"
+                          example: "pg_dump -h $DB_HOST -U $DB_USER -d $DB_NAME -F c -f /backups/$BACKUP_FILE"
+
+                        verification:
+                          type: object
+                          required: false
+                          description: "How to verify the step succeeded"
+                          children:
+                            method:
+                              type: enum
+                              required: true
+                              enum_values:
+                                - command
+                                - visual_check
+                                - log_check
+                                - api_check
+                                - manual_confirmation
+                                - automated_test
+                            check:
+                              type: string
+                              required: true
+                              description: "The specific check to perform"
+                            expected:
+                              type: string
+                              required: true
+                              description: "Expected result of the check"
+
+                        on_failure:
+                          type: object
+                          required: false
+                          description: "What to do if this step fails"
+                          children:
+                            action:
+                              type: enum
+                              required: true
+                              enum_values:
+                                - retry
+                                - skip
+                                - abort
+                                - escalate
+                                - rollback
+                                - alternate_path
+                            max_retries:
+                              type: number
+                              required: false
+                              default: 0
+                            retry_delay:
+                              type: string
+                              required: false
+                              description: "ISO 8601 duration between retries"
+                            escalate_to:
+                              type: string
+                              required: false
+                            rollback_to:
+                              type: string
+                              required: false
+                              description: "Step ID to rollback to"
+                            alternate_step:
+                              type: string
+                              required: false
+                              description: "Step ID of alternate path"
+
+                        decision:
+                          type: object
+                          required: false
+                          description: "Branching logic at this step"
+                          children:
+                            condition:
+                              type: string
+                              required: true
+                              description: "The condition to evaluate"
+                            if_true:
+                              type: string
+                              required: true
+                              description: "Step ID to go to if condition is true"
+                            if_false:
+                              type: string
+                              required: true
+                              description: "Step ID to go to if condition is false"
+
+                        confidence:
+                          type: number
+                          required: false
+                          description: "Extraction confidence score (0.0-1.0) if extracted from source"
+                          constraints:
+                            min: 0.0
+                            max: 1.0
+
+                        notes:
+                          type: string
+                          required: false
+                          description: "Additional context for human reviewers"
+
+                        warnings:
+                          type: array
+                          required: false
+                          items:
+                            type: object
+                            children:
+                              level:
+                                type: enum
+                                required: true
+                                enum_values:
+                                  - info
+                                  - caution
+                                  - warning
+                                  - danger
+                              message:
+                                type: string
+                                required: true
+
+        # --- EXCEPTION HANDLING SECTION ---
+        exception_handling:
+          type: array
+          required: false
+          description: "Documented exceptions and their resolution procedures"
+          items:
+            type: object
+            children:
+              exception_id:
+                type: string
+                required: true
+                constraints:
+                  pattern: "^EX\\d{3}$"
+              trigger:
+                type: string
+                required: true
+                description: "What causes this exception"
+              severity:
+                type: enum
+                required: true
+                enum_values:
+                  - critical
+                  - high
+                  - medium
+                  - low
+              symptoms:
+                type: array
+                required: false
+                items:
+                  type: string
+              resolution:
+                type: array
+                required: true
+                description: "Ordered resolution steps"
+                items:
+                  type: string
+              escalation:
+                type: object
+                required: false
+                children:
+                  to:
+                    type: string
+                    required: true
+                  sla:
+                    type: string
+                    required: false
+                    description: "Expected response time"
+              prevention:
+                type: string
+                required: false
+                description: "How to prevent this exception"
+
+        # --- QUALITY CRITERIA SECTION ---
+        quality_criteria:
+          type: object
+          required: true
+          description: "Measurable quality standards for this process"
+          children:
+
+            kpis:
+              type: array
+              required: true
+              items:
+                type: object
+                children:
+                  kpi_id:
+                    type: string
+                    required: true
+                  name:
+                    type: string
+                    required: true
+                  target:
+                    type: string
+                    required: true
+                  unit:
+                    type: string
+                    required: true
+                  measurement_method:
+                    type: string
+                    required: false
+                  frequency:
+                    type: enum
+                    required: false
+                    enum_values:
+                      - per_execution
+                      - daily
+                      - weekly
+                      - monthly
+                      - quarterly
+
+            acceptance_criteria:
+              type: array
+              required: true
+              items:
+                type: object
+                children:
+                  criteria:
+                    type: string
+                    required: true
+                  measurable:
+                    type: boolean
+                    required: true
+                  threshold:
+                    type: string
+                    required: false
+
+        # --- REVISION HISTORY SECTION ---
+        revision_history:
+          type: array
+          required: true
+          description: "Change log for this SOP"
+          items:
+            type: object
+            children:
+              version:
+                type: string
+                required: true
+              date:
+                type: string
+                required: true
+                constraints:
+                  format: "date"
+              author:
+                type: string
+                required: true
+              changes:
+                type: string
+                required: true
+              approved_by:
+                type: string
+                required: false
+
+  # ===========================================================================
+  # VALIDATION RULES
+  # ===========================================================================
+  validation_rules:
+    - rule: "All step_ids must be unique within the document"
+      type: uniqueness
+      scope: "sop_ml.procedure.phases[*].steps[*].step_id"
+
+    - rule: "All phase_ids must be unique within the document"
+      type: uniqueness
+      scope: "sop_ml.procedure.phases[*].phase_id"
+
+    - rule: "All exception_ids must be unique within the document"
+      type: uniqueness
+      scope: "sop_ml.exception_handling[*].exception_id"
+
+    - rule: "Decision if_true and if_false must reference existing step_ids"
+      type: referential_integrity
+      scope: "sop_ml.procedure.phases[*].steps[*].decision"
+
+    - rule: "on_failure.rollback_to must reference an existing step_id"
+      type: referential_integrity
+      scope: "sop_ml.procedure.phases[*].steps[*].on_failure.rollback_to"
+
+    - rule: "on_failure.alternate_step must reference an existing step_id"
+      type: referential_integrity
+      scope: "sop_ml.procedure.phases[*].steps[*].on_failure.alternate_step"
+
+    - rule: "RACI activity names should correspond to phase or step names"
+      type: consistency
+      scope: "sop_ml.raci[*].activity"
+
+    - rule: "At least one KPI must be defined"
+      type: minimum_count
+      scope: "sop_ml.quality_criteria.kpis"
+      min: 1
+
+    - rule: "At least one acceptance criterion must be defined"
+      type: minimum_count
+      scope: "sop_ml.quality_criteria.acceptance_criteria"
+      min: 1
+
+    - rule: "At least one revision history entry must exist"
+      type: minimum_count
+      scope: "sop_ml.revision_history"
+      min: 1
+
+    - rule: "last_updated must be >= created_date"
+      type: date_comparison
+      scope: "sop_ml.metadata"
+
+    - rule: "confidence scores, if present, must be between 0.0 and 1.0"
+      type: range
+      scope: "sop_ml.procedure.phases[*].steps[*].confidence"
+
+  # ===========================================================================
+  # EXAMPLES
+  # ===========================================================================
+  # Full examples (minimal + comprehensive) extracted to:
+  #   data/sop-ml-schema-examples.yaml
+  # This keeps the schema definition lean for agent context loading.
+  # Agents creating ML SOPs should Read() sop-ml-schema-examples.yaml
+  # when they need concrete reference examples.