{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://jellylabs.ai/schemas/iteration_state.schema.json",
  "title": "DIDP Iteration State",
  "description": "Schema for DIDP v1 iteration state document - the single source of truth for iteration progress",
  "type": "object",
  "required": ["spec_version", "iteration_id", "goal", "phase"],
  "properties": {
    "spec_version": {
      "type": "string",
      "description": "DIDP specification version",
      "enum": ["v1"]
    },
    "provider": {
      "type": "string",
      "description": "Organization or project providing the iteration",
      "examples": ["jellylabs.ai"]
    },
    "iteration_id": {
      "type": "string",
      "description": "Unique identifier for this iteration",
      "pattern": "^ITER-[0-9]{4}-[0-9]{2}-[0-9]{2}-[A-Z]$",
      "examples": ["ITER-2025-12-28-A"]
    },
    "goal": {
      "type": "string",
      "description": "Brief description of iteration objective"
    },
    "branch": {
      "type": "string",
      "description": "Git branch for this iteration",
      "examples": ["master", "iter/ITER-2025-12-28-A"]
    },
    "created": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when iteration was created"
    },
    "phase": {
      "type": "object",
      "description": "Current phase state",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Current phase name",
          "enum": ["planning", "analysis", "spec_lock", "implementation", "testing", "archive", "merge", "complete"]
        },
        "entered": {
          "type": "string",
          "format": "date-time",
          "description": "When current phase was entered"
        },
        "cycle": {
          "type": "integer",
          "minimum": 1,
          "description": "Phase cycle number (for repeated phases like testing)"
        }
      }
    },
    "scope": {
      "type": "object",
      "description": "Iteration scope boundaries",
      "properties": {
        "in": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Items explicitly in scope"
        },
        "out": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Items explicitly out of scope"
        }
      }
    },
    "deliverables": {
      "type": "array",
      "description": "Expected outputs from this iteration",
      "items": {
        "type": "object",
        "required": ["path", "status"],
        "properties": {
          "path": {
            "type": "string",
            "description": "File path or identifier for deliverable"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "in_progress", "complete", "blocked"],
            "description": "Deliverable status"
          },
          "description": {
            "type": "string",
            "description": "Brief description of the deliverable"
          }
        }
      }
    },
    "exit_criteria": {
      "type": "object",
      "description": "Criteria that must be met to exit each phase",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["description", "met"],
          "properties": {
            "description": {
              "type": "string",
              "description": "Exit criterion description"
            },
            "met": {
              "type": "boolean",
              "description": "Whether criterion is satisfied"
            }
          }
        }
      }
    },
    "analysis_outcome": {
      "type": "object",
      "description": "Results from analysis phase (if applicable)",
      "properties": {
        "replan_required": {
          "type": "boolean",
          "description": "Whether replanning is needed"
        },
        "reason": {
          "type": "string",
          "description": "Explanation for replan requirement"
        }
      }
    },
    "handoff_notes": {
      "type": "object",
      "description": "Context for session handoff or resumption",
      "properties": {
        "context": {
          "type": "string",
          "description": "Brief context summary"
        },
        "completed": {
          "type": "array",
          "items": { "type": "string" },
          "description": "What was completed"
        },
        "next_recommended_action": {
          "type": "string",
          "description": "Suggested next step for resuming agent"
        },
        "notes": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Additional notes"
        },
        "previous_iteration": {
          "type": "string",
          "description": "ID of previous iteration (if continuation)"
        }
      }
    }
  }
}