reporting-governance-plugin/schemas/reporting-governance/decision.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cowbay.org/schemas/reporting-governance/decision.schema.json",
  "title": "Reporting Governance Decision",
  "description": "Canonical policy decision schema for the reporting-governance plugin.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "decision",
    "policy_id",
    "severity",
    "reason",
    "rewritten_message",
    "suggested_status",
    "required_actions",
    "operator_notice"
  ],
  "properties": {
    "decision": {
      "$ref": "#/$defs/decision",
      "description": "Canonical enforcement disposition."
    },
    "policy_id": {
      "type": "string",
      "minLength": 1,
      "description": "Stable policy rule identifier that produced the decision."
    },
    "severity": {
      "$ref": "#/$defs/severity",
      "description": "Risk or urgency classification for the decision."
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "description": "Human-readable rationale for the decision."
    },
    "rewritten_message": {
      "type": ["string", "null"],
      "description": "Replacement or annotated outgoing message text when governance rewrites or forces placeholder disclosure."
    },
    "suggested_status": {
      "$ref": "#/$defs/suggestedStatusOrNull",
      "description": "Recommended workflow status after enforcement, if any."
    },
    "required_actions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/requiredAction"
      },
      "description": "Ordered list of required enforcement actions."
    },
    "operator_notice": {
      "$ref": "#/$defs/operatorNoticeOrNull",
      "description": "Operator-visible notice requirement produced by the policy."
    }
  },
  "$defs": {
    "decision": {
      "type": "string",
      "enum": [
        "allow",
        "rewrite",
        "block",
        "require_review",
        "force_checkpoint",
        "escalate",
        "downgrade_status",
        "annotate_placeholder"
      ]
    },
    "severity": {
      "type": "string",
      "enum": [
        "info",
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "suggestedStatus": {
      "type": "string",
      "enum": [
        "in_progress",
        "pending_verification",
        "blocked",
        "failed",
        "awaiting_review",
        "completed"
      ]
    },
    "suggestedStatusOrNull": {
      "oneOf": [
        {
          "$ref": "#/$defs/suggestedStatus"
        },
        {
          "type": "null"
        }
      ]
    },
    "actionVerb": {
      "type": "string",
      "enum": [
        "dispatch_message",
        "rewrite_message",
        "append_audit_note",
        "block_transition",
        "set_status",
        "request_review",
        "emit_event",
        "notify_operator",
        "start_watchdog",
        "raise_escalation",
        "record_placeholder"
      ]
    },
    "actionTarget": {
      "type": "string",
      "enum": [
        "outgoing_report",
        "status_transition",
        "operator_channel",
        "task_record",
        "event_stream",
        "watchdog",
        "review_queue"
      ]
    },
    "requiredAction": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "action",
        "target",
        "mandatory"
      ],
      "properties": {
        "action": {
          "$ref": "#/$defs/actionVerb"
        },
        "target": {
          "$ref": "#/$defs/actionTarget"
        },
        "mandatory": {
          "type": "boolean"
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "urgency": {
      "type": "string",
      "enum": [
        "info",
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "operatorNotice": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "required",
        "channel",
        "urgency",
        "message",
        "deadline"
      ],
      "properties": {
        "required": {
          "type": "boolean"
        },
        "channel": {
          "type": ["string", "null"]
        },
        "urgency": {
          "oneOf": [
            {
              "$ref": "#/$defs/urgency"
            },
            {
              "type": "null"
            }
          ]
        },
        "message": {
          "type": ["string", "null"]
        },
        "must_reference": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "deadline": {
          "type": ["string", "null"],
          "format": "date-time"
        }
      }
    },
    "operatorNoticeOrNull": {
      "oneOf": [
        {
          "$ref": "#/$defs/operatorNotice"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "decision": {
            "const": "rewrite"
          }
        },
        "required": ["decision"]
      },
      "then": {
        "properties": {
          "rewritten_message": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "decision": {
            "const": "annotate_placeholder"
          }
        },
        "required": ["decision"]
      },
      "then": {
        "properties": {
          "rewritten_message": {
            "type": "string",
            "minLength": 1
          },
          "operator_notice": {
            "$ref": "#/$defs/operatorNotice"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "decision": {
            "const": "force_checkpoint"
          }
        },
        "required": ["decision"]
      },
      "then": {
        "properties": {
          "operator_notice": {
            "$ref": "#/$defs/operatorNotice"
          }
        },
        "allOf": [
          {
            "properties": {
              "operator_notice": {
                "properties": {
                  "required": {
                    "const": true
                  }
                },
                "required": ["required"]
              }
            }
          },
          {
            "properties": {
              "required_actions": {
                "contains": {
                  "type": "object",
                  "properties": {
                    "action": {
                      "enum": ["notify_operator", "dispatch_message"]
                    },
                    "mandatory": {
                      "const": true
                    }
                  },
                  "required": ["action", "mandatory"]
                }
              }
            }
          }
        ]
      }
    },
    {
      "if": {
        "properties": {
          "decision": {
            "const": "downgrade_status"
          }
        },
        "required": ["decision"]
      },
      "then": {
        "properties": {
          "suggested_status": {
            "const": "pending_verification"
          },
          "required_actions": {
            "contains": {
              "type": "object",
              "properties": {
                "action": {
                  "const": "set_status"
                },
                "mandatory": {
                  "const": true
                },
                "details": {
                  "type": "object",
                  "properties": {
                    "to": {
                      "const": "pending_verification"
                    }
                  },
                  "required": ["to"]
                }
              },
              "required": ["action", "mandatory", "details"]
            }
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "decision": {
            "const": "block"
          }
        },
        "required": ["decision"]
      },
      "then": {
        "properties": {
          "required_actions": {
            "contains": {
              "type": "object",
              "properties": {
                "action": {
                  "const": "block_transition"
                },
                "mandatory": {
                  "const": true
                }
              },
              "required": ["action", "mandatory"]
            }
          }
        }
      }
    }
  ]
}