{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Agent Ruleset Contract v1.0",
  "description": "Schema describing the ordered phases, steps, and rules that govern agent execution.",
  "type": "object",
  "required": ["contractVersion", "profile", "version", "phases"],
  "properties": {
    "contractVersion": {
      "type": "string",
      "description": "Version of the agent rules contract the payload adheres to."
    },
    "profile": {
      "type": "string",
      "description": "Profile identifier the ruleset targets (e.g., general, agi-code)."
    },
    "version": {
      "type": "string",
      "description": "Semantic or date-based version of the ruleset."
    },
    "label": {
      "type": "string",
      "description": "Optional human readable name for the ruleset."
    },
    "description": {
      "type": "string",
      "description": "Optional long form description for the ruleset."
    },
    "globalPrinciples": {
      "type": "array",
      "description": "Rules that apply to every phase and step.",
      "items": {
        "$ref": "#/definitions/Rule"
      }
    },
    "phases": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/Phase"
      },
      "description": "Ordered phases the agent should move through."
    },
    "metadata": {
      "type": "object",
      "description": "Optional implementation specific metadata."
    }
  },
  "definitions": {
    "Phase": {
      "type": "object",
      "required": ["id", "label", "steps"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier for the phase."
        },
        "label": {
          "type": "string",
          "description": "Display name for operators."
        },
        "description": {
          "type": "string",
          "description": "What the phase accomplishes."
        },
        "trigger": {
          "type": "string",
          "description": "Events or conditions that start the phase."
        },
        "steps": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/Step"
          },
          "description": "Steps within the phase."
        },
        "metadata": {
          "type": "object",
          "description": "Additional data used by tooling."
        }
      }
    },
    "Step": {
      "type": "object",
      "required": ["id", "title", "rules"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier for the step."
        },
        "title": {
          "type": "string",
          "description": "Name of the step."
        },
        "description": {
          "type": "string",
          "description": "High-level summary of the step."
        },
        "intent": {
          "type": "string",
          "description": "Goal the agent should accomplish."
        },
        "entryCriteria": {
          "type": "array",
          "description": "Conditions that must be true before the step begins.",
          "items": {
            "type": "string"
          }
        },
        "exitCriteria": {
          "type": "array",
          "description": "Conditions that must be satisfied before leaving the step.",
          "items": {
            "type": "string"
          }
        },
        "allowedTools": {
          "type": "array",
          "description": "Tool IDs explicitly allowed during the step.",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "blockedTools": {
          "type": "array",
          "description": "Tool IDs that are prohibited while inside the step.",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        },
        "notes": {
          "type": "array",
          "description": "Free-form operator notes for the step.",
          "items": {
            "type": "string"
          }
        },
        "rules": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/Rule"
          },
          "description": "Rules that must be followed while executing the step."
        },
        "subSteps": {
          "type": "array",
          "description": "Nested sub-steps that inherit context from the parent.",
          "items": {
            "$ref": "#/definitions/Step"
          }
        },
        "metadata": {
          "type": "object",
          "description": "Implementation specific details."
        }
      }
    },
    "Rule": {
      "type": "object",
      "required": ["id", "summary", "severity"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable identifier for the rule."
        },
        "summary": {
          "type": "string",
          "description": "Short instruction that must be enforced."
        },
        "detail": {
          "type": "string",
          "description": "Extended rationale or clarification."
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "required", "recommended"],
          "description": "How strictly the rule must be enforced."
        },
        "appliesDuring": {
          "type": "array",
          "description": "Optional labels describing where the rule applies (analysis, planning, edits, etc.).",
          "items": {
            "type": "string"
          }
        },
        "evidenceRequired": {
          "type": "string",
          "description": "Evidence the agent must cite when reporting compliance."
        },
        "references": {
          "type": "array",
          "description": "Supporting documentation for the rule.",
          "items": {
            "$ref": "#/definitions/Reference"
          }
        },
        "toolHints": {
          "type": "array",
          "description": "Suggested tools for satisfying the rule.",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object",
          "description": "Implementation specific metadata."
        }
      }
    },
    "Reference": {
      "type": "object",
      "required": ["label"],
      "properties": {
        "label": {
          "type": "string",
          "description": "Human readable name for the reference."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Optional link to supporting documentation."
        },
        "file": {
          "type": "string",
          "description": "Workspace relative file reference."
        },
        "line": {
          "type": "integer",
          "minimum": 1,
          "description": "Line number in the referenced file."
        }
      }
    }
  }
}