{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://miguelcolmenares.com/schemas/plan-state/v1.schema.json",
  "title": "Paired plan state file",
  "description": "Execution state for a paired plan: docs/{feature}-plan.json answers where the work is, and docs/{feature}-plan.md answers why.",
  "type": "object",
  "required": [
    "planId",
    "title",
    "lifecycle",
    "createdDate",
    "lastUpdated",
    "relatedDocs",
    "taskTemplate",
    "workItems",
    "changelog"
  ],
  "properties": {
    "$schema": {
      "type": "string"
    },
    "planId": {
      "type": "string",
      "minLength": 1
    },
    "title": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "lifecycle": {
      "type": "string",
      "enum": [
        "single-pr",
        "multi-session"
      ]
    },
    "createdDate": {
      "type": "string",
      "format": "date"
    },
    "lastUpdated": {
      "type": "string",
      "format": "date"
    },
    "relatedDocs": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "taskTemplate": {
      "$ref": "#/$defs/taskTemplate"
    },
    "workItems": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/workItem"
      }
    },
    "changelog": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/logEntry"
      }
    },
    "handoff": {
      "$ref": "#/$defs/handoff"
    },
    "externalRef": {
      "$ref": "#/$defs/externalRef"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "$defs": {
    "externalRef": {
      "type": "object",
      "required": [
        "tracker",
        "key",
        "url"
      ],
      "properties": {
        "tracker": {
          "enum": [
            "jira",
            "github"
          ]
        },
        "key": {
          "type": "string",
          "minLength": 1
        },
        "url": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://[^\\s/?#@]+/"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "tracker": {
                "const": "github"
              }
            }
          },
          "then": {
            "properties": {
              "key": {
                "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+#[1-9][0-9]*$"
              },
              "url": {
                "pattern": "^https://[^\\s/?#@]+/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/issues/[1-9][0-9]*/?$"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "tracker": {
                "const": "jira"
              }
            }
          },
          "then": {
            "properties": {
              "key": {
                "pattern": "^[A-Z][A-Z0-9_]*-[1-9][0-9]*$"
              },
              "url": {
                "pattern": "^https://[^\\s/?#@]+(?:/[^\\s/?#]+)*/browse/[A-Z][A-Z0-9_]*-[1-9][0-9]*/?$"
              }
            }
          }
        }
      ],
      "additionalProperties": false
    },
    "handoff": {
      "type": "object",
      "required": [
        "nextAction"
      ],
      "properties": {
        "nextAction": {
          "type": "string",
          "minLength": 1
        },
        "branch": {
          "type": "string"
        },
        "lastCommit": {
          "type": "string"
        },
        "uncommitted": {
          "type": "string",
          "description": "A summary of the uncommitted work, or none."
        },
        "verify": {
          "type": "string",
          "description": "A command or a check that proves the next step worked."
        },
        "updatedBy": {
          "type": "string",
          "description": "The agent and model that wrote the handoff, for example claude-code/sonnet."
        },
        "updatedAt": {
          "type": "string",
          "format": "date"
        }
      },
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "not-started",
        "in-progress",
        "blocked",
        "completed"
      ]
    },
    "templateStep": {
      "type": "object",
      "required": [
        "id",
        "description",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": "string",
          "minLength": 1
        },
        "status": {
          "$ref": "#/$defs/status"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "taskTemplate": {
      "type": "object",
      "required": [
        "steps"
      ],
      "properties": {
        "note": {
          "type": "string"
        },
        "steps": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/templateStep"
          }
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "taskStatus": {
      "type": "object",
      "required": [
        "id",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "status": {
          "$ref": "#/$defs/status"
        },
        "notes": {
          "type": "string"
        },
        "acceptance": {
          "type": "string",
          "description": "The check that makes the task done."
        },
        "files": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "dependsOn": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "claimedBy": {
          "type": "string",
          "description": "The agent and model that claimed the task, for example codex."
        },
        "claimedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "string",
              "format": "date-time"
            }
          ]
        },
        "externalRef": {
          "$ref": "#/$defs/externalRef"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "logEntry": {
      "type": "object",
      "required": [
        "date",
        "summary"
      ],
      "properties": {
        "date": {
          "type": "string",
          "format": "date"
        },
        "summary": {
          "type": "string",
          "minLength": 1
        },
        "agent": {
          "type": "string",
          "description": "The agent and model that wrote the entry."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "workItem": {
      "type": "object",
      "required": [
        "id",
        "title",
        "status",
        "findings",
        "tasks",
        "log"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "type": "string"
        },
        "status": {
          "$ref": "#/$defs/status"
        },
        "path": {
          "type": "string"
        },
        "notes": {
          "type": "string"
        },
        "findings": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tasks": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/taskStatus"
          }
        },
        "log": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/logEntry"
          }
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}