{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/welkaim/ea-codex/schemas/v1/agent-contract.json",
  "title": "AgentContract",
  "description": "Bounded contract for an enterprise AI agent. Binds business intent, semantic context, source policy, design decisions, controls, and feedback into one governed unit. Introduced in Chapter 10. All sub-fields use camelCase; the artifact uses the standard metadata + spec envelope.",
  "type": "object",
  "required": ["apiVersion", "kind", "metadata", "spec"],
  "properties": {
    "apiVersion": { "$ref": "_common.json#/$defs/apiVersion" },
    "kind": { "type": "string", "const": "AgentContract" },
    "metadata": { "$ref": "_common.json#/$defs/metadata" },
    "spec": {
      "type": "object",
      "required": ["intent", "controls", "feedback"],
      "properties": {
        "intent": {
          "type": "object",
          "required": ["capability", "objective", "delegationLevel"],
          "properties": {
            "capability": { "type": "string" },
            "objective": { "type": "string" },
            "delegationLevel": { "$ref": "_common.json#/$defs/delegationLevel" },
            "serviceBoundaries": {
              "type": "object",
              "properties": {
                "allowed": {
                  "type": "array",
                  "items": { "type": "string" }
                },
                "forbidden": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              },
              "additionalProperties": true
            }
          },
          "additionalProperties": true
        },
        "semanticModel": {
          "type": "object",
          "properties": {
            "entities": {
              "type": "array",
              "items": { "type": "string" }
            },
            "authoritativeRelations": {
              "type": "array",
              "items": { "type": "string" }
            },
            "glossaryPack": { "type": "string" },
            "decisionPack": { "type": "string" }
          },
          "additionalProperties": true
        },
        "sourcePolicy": {
          "type": "object",
          "properties": {
            "authoritative": { "type": "array", "items": { "type": "string" } },
            "conditional": { "type": "array", "items": { "type": "string" } },
            "prohibited": { "type": "array", "items": { "type": "string" } }
          },
          "additionalProperties": true
        },
        "designDecisions": {
          "type": "object",
          "properties": {
            "retrievalRequired": { "type": "boolean" },
            "retrievalMustBeScopedBy": {
              "type": "array",
              "items": { "type": "string" }
            },
            "sourcePrecedence": {
              "type": "array",
              "items": { "type": "string" }
            },
            "answerMustInclude": {
              "type": "array",
              "items": { "type": "string" }
            },
            "actionProfile": {
              "type": "string",
              "enum": ["readOnly", "readWriteWithApproval", "write"]
            },
            "mandatoryEscalationConditions": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "additionalProperties": true
        },
        "controls": {
          "type": "object",
          "properties": {
            "inputGuardrails": {
              "type": "array",
              "items": { "type": "string" }
            },
            "outputRules": {
              "type": "array",
              "items": { "type": "string" }
            },
            "humanReview": {
              "type": "object",
              "properties": {
                "requiredBefore": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              },
              "additionalProperties": true
            },
            "trace": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "additionalProperties": true
        },
        "feedback": {
          "type": "object",
          "required": ["evaluateOn"],
          "properties": {
            "evaluateOn": {
              "type": "array",
              "items": { "type": "string" },
              "minItems": 1
            },
            "reviewCadence": { "type": "string" }
          },
          "additionalProperties": true
        },
        "governance": {
          "type": "object",
          "description": "Optional block carrying the agent's role inside an enterprise governance body (council, ARB, design board). Present when the agent participates in collective deliberation rather than acting in isolation. Introduced in Chapter 4 to model AI-augmented design authority without forcing a separate kind.",
          "properties": {
            "designAuthorityBodyRef": {
              "type": "string",
              "description": "Identifier of the DesignAuthorityBody this agent participates in."
            },
            "governanceRole": {
              "type": "string",
              "enum": [
                "advisor",
                "evaluator",
                "orchestrator",
                "challenger",
                "escalator",
                "veto-holder"
              ],
              "description": "Role the agent plays inside the body. 'advisor' produces non-binding findings; 'evaluator' produces structured assessments for human approval; 'orchestrator' coordinates other agents and synthesizes findings; 'challenger' performs adversarial review without approval rights; 'escalator' routes findings to higher authority; 'veto-holder' may block on stated grounds."
            },
            "delegationLevelsHandled": {
              "type": "array",
              "items": { "$ref": "_common.json#/$defs/delegationLevel" },
              "description": "Which delegation levels (defined in the referenced DelegationPolicy) this agent operates at."
            },
            "skills": {
              "type": "array",
              "description": "Named capabilities the agent carries. Each skill has an id, the delegation level it operates at, and a description.",
              "items": {
                "type": "object",
                "required": ["id", "level", "description"],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Skill identifier (e.g. 'skill.classify-data-touchpoint', 'skill.assess-validated-system-impact')."
                  },
                  "level": { "$ref": "_common.json#/$defs/delegationLevel" },
                  "description": {
                    "type": "string",
                    "description": "What the skill does."
                  },
                  "skillType": {
                    "type": "string",
                    "enum": ["assessment", "generation"],
                    "description": "Whether the skill produces findings (assessment) or produces draft governance artifacts from templates (generation). Defaults to 'assessment' if omitted."
                  },
                  "templateRef": {
                    "type": "string",
                    "description": "For generation skills: pointer to the governed template the skill produces drafts from."
                  },
                  "contextRequired": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "For generation skills: Codex context the skill must retrieve before drafting. Examples: 'codex:capability-definition', 'codex:applicable-policies'."
                  },
                  "outputArtifact": {
                    "type": "string",
                    "description": "For generation skills: identifier of the artifact type the skill produces (e.g. 'dpia-draft', 'change-impact-assessment-draft')."
                  },
                  "approvalAuthority": {
                    "type": "string",
                    "description": "For generation skills: human role authorized to approve the draft."
                  }
                },
                "additionalProperties": true
              }
            },
            "humanEscalation": {
              "type": "object",
              "description": "Conditions under which the agent must escalate findings to a human, beyond the routine humanReview controls.",
              "properties": {
                "requireArchitectReview": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "Conditions that require a domain architect to review (e.g. 'finding_type:data_classification_conflict', 'finding_severity:high')."
                },
                "escalateToBoard": {
                  "type": "array",
                  "items": { "type": "string" },
                  "description": "Conditions that escalate to the design authority board (e.g. 'finding_type:cross_domain_data_authority_change')."
                }
              },
              "additionalProperties": true
            },
            "evaluationMetrics": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Metrics the enterprise tracks to evaluate the agent's governance contribution. Examples: 'overrideRate', 'falsePositiveRate', 'timeToFindingSeconds', 'escalationAccuracy'."
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}