{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"$id": "https://test-gate.moinsen.dev/schemas/run-v1.json",
	"title": "test-gate run file (v1)",
	"description": "A live-test gate's state: top-level metadata, findings cross-linked to items, and one or more sessions of verification items. The run-file is updated in place by the test-gate web-UI; the JSON is the source of truth.",
	"type": "object",
	"required": ["schema_version", "run", "sessions"],
	"properties": {
		"$schema": { "type": "string" },
		"schema_version": {
			"type": "integer",
			"const": 1,
			"description": "Bumps when the schema changes incompatibly."
		},
		"run": {
			"type": "object",
			"required": ["title", "version"],
			"properties": {
				"title": { "type": "string" },
				"version": { "type": "string" },
				"build": { "type": ["string", "null"] },
				"createdAt": { "type": ["string", "null"], "format": "date-time" },
				"scope": { "type": "string" },
				"verdict": {
					"type": ["string", "null"],
					"enum": [null, "pass", "fail"]
				}
			}
		},
		"findings": {
			"type": "array",
			"items": {
				"type": "object",
				"required": ["id", "what"],
				"properties": {
					"id": { "type": "string" },
					"what": { "type": "string" },
					"severity": {
						"type": "string",
						"description": "Free-text. Common values: 'ux-small', 'ux-medium', 'ux-large', 'build-hygiene', 'mittel', 'klein', 'spike', 'data-loss'."
					},
					"status": {
						"type": "string",
						"enum": ["open", "fixed", "parked", "deferred"]
					},
					"linkedItems": {
						"type": "array",
						"items": { "type": "string" },
						"description": "IDs of items in any session that this finding cross-links to."
					}
				}
			}
		},
		"sessions": {
			"type": "array",
			"minItems": 1,
			"items": {
				"type": "object",
				"required": ["id", "title", "items"],
				"properties": {
					"id": { "type": "string" },
					"title": { "type": "string" },
					"intro": { "type": "string", "description": "Optional markdown shown above the items." },
					"items": {
						"type": "array",
						"items": {
							"type": "object",
							"required": ["id", "title"],
							"properties": {
								"id": {
									"type": "string",
									"description": "Author-chosen short ID. Must be unique across all sessions in this run."
								},
								"title": { "type": "string" },
								"why": { "type": "string", "description": "Optional markdown — one or two sentences explaining why this item exists (which slice, what regression it guards against). Renders above `do` so the human keeps context across long runs. Added in v0.2.0." },
								"do": { "type": "string", "description": "Markdown — what the human should do." },
								"expected": { "type": "string", "description": "Markdown — observable outcome that means PASS." },
								"status": {
									"type": "string",
									"enum": ["pending", "pass", "fail", "skip", "blocked", "cr"],
									"description": "`cr` = Change Request — the item works as specified, but the human noted a follow-up improvement. Counts as PASS for verdict purposes; surfaces as a separate bucket in summaries.",
									"default": "pending"
								},
								"note": { "type": "string", "default": "" },
								"screenshots": {
									"type": "array",
									"items": { "type": "string" },
									"description": "Paths relative to the run-file's directory."
								},
								"updatedAt": { "type": ["string", "null"], "format": "date-time" }
							}
						}
					}
				}
			}
		}
	}
}