{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Grid State",
  "description": "Schema for .grid/STATE.md YAML frontmatter. Tracks mission progress, current position, and active programs.",
  "type": "object",
  "required": ["mission", "status"],
  "properties": {
    "mission": {
      "type": "string",
      "description": "The current mission being executed"
    },
    "cluster": {
      "type": "string",
      "description": "Name of the mission cluster"
    },
    "status": {
      "type": "string",
      "enum": ["planning", "executing", "verifying", "checkpoint", "paused", "complete", "failed"],
      "description": "Current execution status"
    },
    "phase": {
      "type": "string",
      "pattern": "^[0-9]{2}$",
      "description": "Current phase ID (01, 02, etc.)"
    },
    "phaseName": {
      "type": "string",
      "description": "Human-readable name of current phase"
    },
    "block": {
      "type": "string",
      "pattern": "^[0-9]{2}-[0-9]{2}$",
      "description": "Current block ID (01-01, 01-02, etc.)"
    },
    "blockName": {
      "type": "string",
      "description": "Human-readable name of current block"
    },
    "wave": {
      "type": "integer",
      "minimum": 1,
      "description": "Current execution wave"
    },
    "thread": {
      "type": "string",
      "pattern": "^[0-9]{2}-[0-9]{2}-[0-9]{2}$",
      "description": "Current thread ID if executing"
    },
    "active_programs": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of currently active spawned programs"
    },
    "total_programs_spawned": {
      "type": "integer",
      "minimum": 0,
      "description": "Total programs spawned during this mission"
    },
    "completed_blocks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of completed block IDs"
    },
    "completed_threads": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of completed thread IDs"
    },
    "progress": {
      "type": "object",
      "properties": {
        "phases_complete": {
          "type": "integer",
          "minimum": 0
        },
        "phases_total": {
          "type": "integer",
          "minimum": 1
        },
        "blocks_complete": {
          "type": "integer",
          "minimum": 0
        },
        "blocks_total": {
          "type": "integer",
          "minimum": 1
        },
        "threads_complete": {
          "type": "integer",
          "minimum": 0
        },
        "threads_total": {
          "type": "integer",
          "minimum": 1
        },
        "percentage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        }
      },
      "description": "Progress tracking metrics"
    },
    "checkpoint": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["human-verify", "decision", "human-action"]
        },
        "reason": {
          "type": "string"
        },
        "awaiting": {
          "type": "string",
          "description": "What user action is needed"
        }
      },
      "description": "Current checkpoint details if status is 'checkpoint'"
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when mission started"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of last state update"
    },
    "last_activity": {
      "type": "string",
      "description": "Human-readable description of last activity"
    },
    "resume_file": {
      "type": "string",
      "description": "Path to resume file if mission was paused"
    },
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "block": {
          "type": "string"
        },
        "thread": {
          "type": "string"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time"
        }
      },
      "description": "Error details if status is 'failed'"
    }
  }
}