{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://opencode.kit/schemas/contract.schema.json",
  "title": "OpenCode Orchestration Contract Schema",
  "description": "Top-level fields are all optional to support contract evolution. Use property-specific required constraints for nested mandatory fields.",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "const": "http://json-schema.org/draft-07/schema#",
      "description": "JSON Schema dialect identifier"
    },
    "state": {
      "type": "string",
      "enum": [
        "INIT",
        "PLAN",
        "PLAN_SCORED",
        "EXECUTE",
        "EXECUTE_SCORED",
        "REVIEW",
        "REVIEW_SCORED",
        "COMPLETE",
        "BLOCKED"
      ],
      "description": "Current lifecycle state of the contract"
    },
    "contract_version": {
      "type": "string",
      "description": "Semantic version of the contract schema"
    },
    "session": {
      "type": "object",
      "properties": {
        "task_id": {
          "type": "string"
        },
        "branch": {
          "type": "string"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "model": {
          "type": "string",
          "description": "Current model ID (e.g. 'mimo-v2.5', 'deepseek-v4-flash'). Seeded from opencode.json on init."
        },
        "previous_model": {
          "type": "string",
          "description": "Previous model ID before last model change. Empty if no change has occurred."
        },
        "model_changed_at": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of last model change. Empty if no change has occurred."
        },
        "model_change_count": {
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "description": "Number of model changes during this contract's lifecycle."
        }
      },
      "additionalProperties": true,
      "description": "Session metadata for traceability and resumption"
    },
    "scope": {
      "type": "object",
      "properties": {
        "included": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "excluded": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "boundary": {
          "type": "string",
          "enum": [
            "project-root",
            "subdirectory",
            "single-file",
            "cross-project",
            "custom"
          ]
        },
        "parallel_eligible": {
          "type": "boolean"
        },
        "max_parallel_agents": {
          "type": "integer",
          "minimum": 1
        }
      },
      "additionalProperties": true,
      "description": "Work boundaries and parallelism controls"
    },
    "required_tools": {
      "type": "object",
      "properties": {
        "description": {
          "type": "string"
        },
        "enforced": {
          "type": "boolean"
        },
        "tools": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "required": {
                "type": "boolean"
              },
              "blocked": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "properties": {
            "graphify": {
              "type": "object",
              "properties": {
                "required": {
                  "type": "boolean"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "required": [
        "enforced",
        "tools"
      ],
      "description": "Tool enforcement policy \u2014 lean-ctx_* required, bash blocked"
    },
    "requirements": {
      "type": "object",
      "properties": {
        "goal": {
          "type": "string",
          "minLength": 1,
          "description": "Primary objective of the task"
        },
        "scope": {
          "type": "object",
          "properties": {
            "included": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "In-scope files, directories, or concerns"
            },
            "excluded": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Explicitly out-of-scope items"
            },
            "parallel_eligible": {
              "type": "boolean",
              "description": "Whether this goal supports parallel agent dispatch"
            }
          }
        },
        "success_criteria": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Measurable outcomes that define completion"
        },
        "acceptance_criteria": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "constraints": {
          "type": "object",
          "additionalProperties": true,
          "description": "Constraints and guardrails (may be object or array)"
        }
      },
      "required": [
        "goal"
      ],
      "additionalProperties": true,
      "description": "Task requirements, scope, and definition of done"
    },
    "decisions": {
      "type": "object",
      "properties": {
        "approved_architecture": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "object"
            }
          ],
          "description": "Approved architecture decision or reference"
        },
        "coding_standard": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "rejected_approaches": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "adr_log": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "date": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "description": "Architecture Decision Record log"
        }
      },
      "additionalProperties": true,
      "description": "Architectural decisions and rejected alternatives"
    },
    "governance": {
      "type": "object",
      "properties": {
        "active_agent": {
          "type": "string"
        },
        "mode": {
          "type": "string",
          "enum": [
            "autonomous",
            "supervised",
            "interactive"
          ]
        },
        "applicable_skills": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "current_guidance": {
          "type": "string",
          "description": "Active execution guidance for the current agent"
        },
        "rules_references": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "sections": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "source",
              "sections"
            ]
          },
          "description": "References to rule documents governing execution"
        },
        "extension_skills": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Loaded extension skills for this session"
        },
        "permissions": {
          "type": "object",
          "properties": {
            "do": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "dont": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "allowed_execution": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "read",
                  "write",
                  "execute",
                  "deploy"
                ]
              }
            }
          },
          "additionalProperties": true
        },
        "previous_blockers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "decisions_log": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "agent": {
                "type": "string"
              },
              "decision": {
                "type": "string"
              },
              "timestamp": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "description": "Historical log of decisions made during execution"
        },
        "timeout": {
          "type": "object",
          "description": "Timeout and resource exhaustion handling",
          "properties": {
            "max_session_minutes": {
              "type": "integer",
              "minimum": 1,
              "default": 60
            },
            "max_retries": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5,
              "default": 2
            },
            "escalation_on_timeout": {
              "type": "string",
              "enum": [
                "retry",
                "handoff",
                "block"
              ],
              "default": "handoff"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": true,
      "description": "Governance and rule enforcement context"
    },
    "validation": {
      "type": "object",
      "properties": {
        "block_on": {
          "type": "object",
          "properties": {
            "max_test_failures": {
              "type": "integer",
              "minimum": 0
            },
            "max_score_drop": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "max_compile_errors": {
              "type": "integer",
              "minimum": 0
            }
          },
          "additionalProperties": true
        },
        "rule_overrides": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": true,
      "description": "Validation thresholds that trigger BLOCKED state"
    },
    "score": {
      "type": "object",
      "properties": {
        "rules": {
          "type": "object",
          "properties": {
            "pass": {
              "type": "integer",
              "minimum": 0
            },
            "fail": {
              "type": "integer",
              "minimum": 0
            },
            "deduction": {
              "type": "number"
            },
            "subtotal": {
              "type": "number"
            }
          },
          "description": "Rule-based scoring breakdown"
        },
        "judge": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "score": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "rationale": {
                  "type": "string"
                },
                "missing_items": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "additionalProperties": true
            },
            {
              "type": "null"
            }
          ],
          "description": "LLM judge evaluation (nullable)"
        },
        "combined": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Combined score (0-100)"
        },
        "verdict": {
          "type": "string",
          "enum": [
            "INIT",
            "PASS",
            "RETRY",
            "BLOCKED"
          ],
          "description": "Overall scoring verdict"
        }
      },
      "additionalProperties": true,
      "description": "Scoring and evaluation results"
    },
    "retry": {
      "type": "object",
      "properties": {
        "attempt": {
          "type": "integer",
          "minimum": 0,
          "description": "Current retry attempt number"
        },
        "max_attempts": {
          "type": "integer",
          "minimum": 1,
          "description": "Maximum allowed retry attempts"
        },
        "current_phase": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Phase being retried"
        },
        "score_threshold": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "escalation_threshold": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of issues that triggered retry"
        }
      },
      "additionalProperties": true,
      "description": "Retry policy and issue tracking"
    },
    "blocked_recovery": {
      "type": "object",
      "description": "How to recover from BLOCKED state",
      "properties": {
        "max_retries": {
          "type": "integer",
          "default": 2
        },
        "escalation_path": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [
            "retry",
            "escalate_to_orchestrator",
            "human_intervention"
          ]
        }
      }
    },
    "outputs": {
      "type": "object",
      "properties": {
        "plan": {
          "type": [
            "object",
            "null"
          ]
        },
        "architecture": {
          "type": [
            "object",
            "null"
          ]
        },
        "code_changes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "file": {
                "type": "string"
              },
              "change_type": {
                "type": "string",
                "enum": [
                  "create",
                  "modify",
                  "delete"
                ]
              },
              "summary": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        },
        "test_results": {
          "type": [
            "object",
            "null"
          ]
        },
        "agent_reports": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "score_summary": {
          "type": [
            "object",
            "null"
          ]
        }
      },
      "additionalProperties": true,
      "description": "Artifacts produced during execution"
    },
    "metrics": {
      "type": "object",
      "properties": {
        "cost_tokens": {
          "type": "integer",
          "minimum": 0
        },
        "elapsed_ms": {
          "type": "integer",
          "minimum": 0
        },
        "agents_used": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "phases_completed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": true,
      "description": "Execution performance metrics"
    },
    "lessons_learned": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string"
          },
          "insight": {
            "type": "string"
          },
          "recommendation": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "description": "Cross-session learning artifacts"
    }
  },
  "additionalProperties": true
}