{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://xbrief.dev/schemas/xbrief-core-0.8.schema.json",
  "title": "xBRIEF Core Schema v0.8",
  "description": "JSON Schema for xBRIEF core document structure (v0.8). Adds PlanItem type (task/group/milestone/epic), summary, planRefs, extension property namespace (x-<consumer>/), Source/Confidence narrative keys, and reference type registry.",
  "type": "object",
  "required": [
    "xBRIEFInfo",
    "plan"
  ],
  "properties": {
    "xBRIEFInfo": {
      "$ref": "#/$defs/xBRIEFInfo"
    },
    "plan": {
      "$ref": "#/$defs/Plan"
    }
  },
  "additionalProperties": true,
  "patternProperties": {
    "^x-[a-z0-9-]+/": {
      "description": "Extension property. Consumer-scoped; MUST be preserved verbatim on round-trip."
    }
  },
  "not": {
    "anyOf": [
      {
        "required": [
          "todoList"
        ]
      },
      {
        "required": [
          "playbook"
        ]
      }
    ]
  },
  "$defs": {
    "xBRIEFInfo": {
      "type": "object",
      "required": [
        "version"
      ],
      "properties": {
        "version": {
          "type": "string",
          "const": "0.8"
        },
        "author": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "metadata": {
          "type": "object"
        },
        "created": {
          "$ref": "#/$defs/dateTime"
        },
        "updated": {
          "$ref": "#/$defs/dateTime"
        },
        "timezone": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "patternProperties": {
        "^x-[a-z0-9-]+/": {}
      }
    },
    "Plan": {
      "type": "object",
      "required": [
        "title",
        "status",
        "items"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*$"
        },
        "uid": {
          "type": "string"
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "status": {
          "$ref": "#/$defs/PlanStatus"
        },
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PlanItem"
          }
        },
        "narratives": {
          "type": "object",
          "properties": {
            "Proposal": {
              "type": "string"
            },
            "Overview": {
              "type": "string"
            },
            "Background": {
              "type": "string"
            },
            "Problem": {
              "type": "string"
            },
            "Constraint": {
              "type": "string"
            },
            "Hypothesis": {
              "type": "string"
            },
            "Alternative": {
              "type": "string"
            },
            "Risk": {
              "type": "string"
            },
            "Test": {
              "type": "string"
            },
            "Action": {
              "type": "string"
            },
            "Observation": {
              "type": "string"
            },
            "Result": {
              "type": "string"
            },
            "Reflection": {
              "type": "string"
            },
            "Outcome": {
              "type": "string"
            },
            "Strengths": {
              "type": "string"
            },
            "Weaknesses": {
              "type": "string"
            },
            "Lessons": {
              "type": "string"
            },
            "Source": {
              "type": "string",
              "description": "How a fact was established (#479). Named classes: verified, observed, inferred, assumed, propagated. Optional :<method-or-reason> suffix. Multiple tokens separated by '; '. Confidence does not substitute for evidence. Bind Source, Evidence, Verifier, and VerifiedAt on this same Plan.narratives object as the atomic claim unit."
            },
            "Confidence": {
              "type": "string",
              "description": "Agent certainty (#479 / #5385). Writers MUST emit high|medium|low. Readers of 0.8 MAY see legacy prose strings; Directive validate warns (Confidence-compat) and does not hard-fail string shape. Does not substitute for Evidence on a verified claim."
            },
            "Evidence": {
              "type": "string",
              "description": "Pointer or event backing the atomic claim unit (#479). Required when Source includes class verified."
            },
            "Verifier": {
              "type": "string",
              "description": "Who or what verified the atomic claim unit (#479). Required when Source includes class verified."
            },
            "VerifiedAt": {
              "$ref": "#/$defs/dateTime",
              "description": "ISO-8601 time of verification for the atomic claim unit (#479). Required when Source includes class verified."
            }
          },
          "additionalProperties": {
            "type": "string"
          }
        },
        "edges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Edge"
          }
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "created": {
          "$ref": "#/$defs/dateTime"
        },
        "updated": {
          "$ref": "#/$defs/dateTime"
        },
        "author": {
          "type": "string"
        },
        "reviewers": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "uris": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          }
        },
        "references": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/VBriefReference"
          }
        },
        "timezone": {
          "type": "string"
        },
        "agent": {
          "$ref": "#/$defs/Agent"
        },
        "lastModifiedBy": {
          "$ref": "#/$defs/Agent"
        },
        "changeLog": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Change"
          }
        },
        "sequence": {
          "type": "integer",
          "minimum": 0
        },
        "fork": {
          "$ref": "#/$defs/Fork"
        },
        "architecture": {
          "$ref": "#/$defs/Architecture"
        }
      },
      "additionalProperties": true,
      "patternProperties": {
        "^x-[a-z0-9-]+/": {}
      }
    },
    "PlanItem": {
      "type": "object",
      "required": [
        "title",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*$"
        },
        "uid": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "task",
            "group",
            "milestone",
            "epic"
          ],
          "default": "task",
          "description": "Item type. Containers (group, milestone, epic) support status rollup."
        },
        "summary": {
          "type": "string",
          "description": "Single-sentence shorthand description. Equivalent to narrative.Overview when narrative is absent."
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "status": {
          "$ref": "#/$defs/PlanItemStatus"
        },
        "narrative": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "subItems": {
          "type": "array",
          "description": "Deprecated legacy alias for items; retained for compatibility.",
          "items": {
            "$ref": "#/$defs/PlanItem"
          }
        },
        "planRef": {
          "type": "string",
          "pattern": "^(#[a-zA-Z0-9_.-]+|file://.*|https://.*)$"
        },
        "planRefs": {
          "type": "array",
          "description": "Array of plan reference URIs for container items aggregating multiple external xBRIEFs.",
          "items": {
            "type": "string",
            "pattern": "^(#[a-zA-Z0-9_.-]+|file://.*|https://.*)$"
          }
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metadata": {
          "type": "object"
        },
        "created": {
          "$ref": "#/$defs/dateTime"
        },
        "updated": {
          "$ref": "#/$defs/dateTime"
        },
        "completed": {
          "$ref": "#/$defs/dateTime"
        },
        "priority": {
          "enum": [
            "low",
            "medium",
            "high",
            "critical"
          ]
        },
        "effort": {
          "type": "string",
          "enum": [
            "S",
            "M",
            "L",
            "XL"
          ],
          "description": "Optional effort estimate with time anchors: S <2h, M half-day (2-4h), L 1-2 days, XL needs breakdown into S/M/L before activation. Omitted items still validate."
        },
        "stopConditions": {
          "type": "array",
          "description": "Optional mid-execution precondition STOP anchors (#1613). Omitted field validates. v1 admits kind:anchor only; on fire halt and report — do not improvise. Distinct from narrative.Acceptance (done criteria).",
          "items": {
            "$ref": "#/$defs/StopConditionAnchor"
          }
        },
        "dueDate": {
          "$ref": "#/$defs/dateTime"
        },
        "startDate": {
          "$ref": "#/$defs/dateTime"
        },
        "endDate": {
          "$ref": "#/$defs/dateTime"
        },
        "percentComplete": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "participants": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Participant"
          }
        },
        "location": {
          "$ref": "#/$defs/Location"
        },
        "uris": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/URI"
          }
        },
        "recurrence": {
          "$ref": "#/$defs/RecurrenceRule"
        },
        "reminders": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Reminder"
          }
        },
        "classification": {
          "enum": [
            "public",
            "private",
            "confidential"
          ]
        },
        "relatedComments": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "timezone": {
          "type": "string"
        },
        "sequence": {
          "type": "integer",
          "minimum": 0
        },
        "lastModifiedBy": {
          "$ref": "#/$defs/Agent"
        },
        "lockedBy": {
          "$ref": "#/$defs/Lock"
        },
        "items": {
          "type": "array",
          "description": "Preferred v0.6 nested PlanItem field.",
          "items": {
            "$ref": "#/$defs/PlanItem"
          }
        }
      },
      "additionalProperties": true,
      "patternProperties": {
        "^x-[a-z0-9-]+/": {}
      }
    },
    "StopConditionAnchor": {
      "type": "object",
      "required": ["id", "kind", "path"],
      "additionalProperties": false,
      "description": "Checkable mid-execution STOP anchor on a PlanItem (#1613). v1 kind is anchor only. At least one of excerpt or digest MUST be present. Absent observeAt means check at item-start and item-resume.",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Stable stop id within the PlanItem."
        },
        "kind": {
          "type": "string",
          "const": "anchor",
          "description": "v1 admits anchor only; assumption kind is deferred."
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "description": "Repo-relative path the anchor cites (no absolute or '..' segments)."
        },
        "excerpt": {
          "type": "string",
          "minLength": 1,
          "description": "Literal excerpt that must still match the live file at the cited path."
        },
        "digest": {
          "type": "string",
          "minLength": 1,
          "description": "Opaque nonempty digest that must equal the agent-computed digest of the live file bytes (convention: lowercase hex SHA-256, optional sha256: prefix)."
        },
        "resolvedAtSha": {
          "type": "string",
          "description": "Optional commit SHA when the anchor was authored — diagnosis / expected-content pin only; live-file match stays authoritative."
        },
        "rationale": {
          "type": "string",
          "description": "Optional human-readable why this anchor matters."
        },
        "observeAt": {
          "type": "string",
          "enum": ["item-start", "item-resume"],
          "description": "When to evaluate. Absent ⇒ check both item-start and item-resume."
        }
      },
      "anyOf": [
        { "required": ["excerpt"] },
        { "required": ["digest"] }
      ]
    },
    "PlanStatus": {
      "enum": [
        "draft",
        "proposed",
        "approved",
        "pending",
        "running",
        "completed",
        "blocked",
        "failed",
        "cancelled"
      ],
      "description": "Status values valid at plan level. 'auto' is excluded — it is only valid on container PlanItems with children."
    },
    "PlanItemStatus": {
      "enum": [
        "draft",
        "proposed",
        "approved",
        "pending",
        "running",
        "completed",
        "blocked",
        "failed",
        "cancelled",
        "auto"
      ],
      "description": "Status values valid on PlanItems. 'auto' rolls up from children and is valid only on container items (group/milestone/epic) with children."
    },
    "Edge": {
      "type": "object",
      "required": [
        "from",
        "to",
        "type"
      ],
      "properties": {
        "from": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*$"
        },
        "to": {
          "type": "string",
          "pattern": "^[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*$"
        },
        "type": {
          "type": "string",
          "description": "Core types: blocks, informs, invalidates, suggests. Custom types allowed."
        }
      },
      "additionalProperties": true
    },
    "Participant": {
      "type": "object",
      "required": [
        "id",
        "role"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "role": {
          "enum": [
            "owner",
            "assignee",
            "reviewer",
            "observer",
            "contributor"
          ]
        },
        "status": {
          "enum": [
            "accepted",
            "declined",
            "tentative",
            "needsAction"
          ]
        }
      },
      "additionalProperties": true
    },
    "URI": {
      "type": "object",
      "required": [
        "uri"
      ],
      "properties": {
        "uri": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": true
    },
    "VBriefReference": {
      "allOf": [
        {
          "$ref": "#/$defs/URI"
        },
        {
          "type": "object",
          "required": [
            "uri",
            "type"
          ],
          "properties": {
            "type": {
              "type": "string",
              "pattern": "^x-[a-zA-Z0-9_-]+/",
              "description": "A xBRIEF reference type. Canonical types: x-xbrief/plan, x-xbrief/github-issue, x-xbrief/github-pr, x-xbrief/commit, x-xbrief/external, x-xbrief/research, x-xbrief/adr. Custom consumer types SHOULD use x-<consumer>/ namespace (e.g. x-myapp/ticket)."
            },
            "TrustLevel": {
              "type": "string",
              "enum": [
                "verified",
                "internal",
                "external"
              ],
              "description": "Trust classification (#480 / #479). verified = confirmed against the working tree; internal = originated inside the trust boundary; external = originated outside. Missing field reads as external, never verified. Promotion from external to verified requires explicit revalidation."
            }
          }
        }
      ]
    },
    "Location": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "geo": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": "number"
          }
        },
        "url": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "RecurrenceRule": {
      "type": "object",
      "required": [
        "frequency"
      ],
      "properties": {
        "frequency": {
          "enum": [
            "daily",
            "weekly",
            "monthly",
            "yearly"
          ]
        },
        "interval": {
          "type": "integer",
          "minimum": 1
        },
        "until": {
          "$ref": "#/$defs/dateTime"
        },
        "count": {
          "type": "integer",
          "minimum": 1
        },
        "byDay": {
          "type": "array",
          "items": {
            "enum": [
              "MO",
              "TU",
              "WE",
              "TH",
              "FR",
              "SA",
              "SU"
            ]
          }
        },
        "byMonth": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12
          }
        },
        "byMonthDay": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 1,
            "maximum": 31
          }
        }
      },
      "additionalProperties": true
    },
    "Reminder": {
      "type": "object",
      "required": [
        "trigger",
        "action"
      ],
      "properties": {
        "trigger": {
          "type": "string"
        },
        "action": {
          "enum": [
            "display",
            "email",
            "webhook",
            "audio"
          ]
        },
        "description": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "Agent": {
      "type": "object",
      "required": [
        "id",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "enum": [
            "human",
            "aiAgent",
            "system"
          ]
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "Change": {
      "type": "object",
      "required": [
        "sequence",
        "timestamp",
        "agent",
        "operation"
      ],
      "properties": {
        "sequence": {
          "type": "integer",
          "minimum": 0
        },
        "timestamp": {
          "$ref": "#/$defs/dateTime"
        },
        "agent": {
          "$ref": "#/$defs/Agent"
        },
        "operation": {
          "enum": [
            "create",
            "update",
            "delete",
            "fork",
            "merge"
          ]
        },
        "reason": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "oldValue": {},
        "newValue": {},
        "description": {
          "type": "string"
        },
        "snapshotUri": {
          "type": "string"
        },
        "relatedChanges": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": true
    },
    "Fork": {
      "type": "object",
      "required": [
        "parentUid",
        "parentSequence",
        "forkedAt"
      ],
      "properties": {
        "parentUid": {
          "type": "string"
        },
        "parentSequence": {
          "type": "integer",
          "minimum": 0
        },
        "forkedAt": {
          "$ref": "#/$defs/dateTime"
        },
        "forkReason": {
          "type": "string"
        },
        "mergeStatus": {
          "enum": [
            "unmerged",
            "mergePending",
            "merged",
            "conflict"
          ]
        }
      },
      "additionalProperties": true
    },
    "Lock": {
      "type": "object",
      "required": [
        "agent",
        "acquiredAt",
        "type"
      ],
      "properties": {
        "agent": {
          "$ref": "#/$defs/Agent"
        },
        "acquiredAt": {
          "$ref": "#/$defs/dateTime"
        },
        "expiresAt": {
          "$ref": "#/$defs/dateTime"
        },
        "type": {
          "enum": [
            "soft",
            "hard"
          ]
        }
      },
      "additionalProperties": true
    },
    "dateTime": {
      "type": "string",
      "format": "date-time",
      "pattern": "(Z|[+-]\\d{2}:\\d{2})$"
    },
    "Architecture": {
      "type": "object",
      "description": "Directive-local architecture metadata (#1595 codeStructure; #1492 systemOfRecord).",
      "properties": {
        "codeStructure": {
          "type": "object",
          "additionalProperties": true
        },
        "systemOfRecord": {
          "$ref": "#/$defs/SystemOfRecord"
        },
        "stateful": {
          "type": "boolean",
          "description": "Author-asserted statefulness opt-in for story-mode SOR applicability (#1492)."
        }
      },
      "additionalProperties": true
    },
    "SystemOfRecord": {
      "type": "object",
      "description": "System-of-record design record. Canonical home: plan.architecture.systemOfRecord (#1492).",
      "properties": {
        "disposition": {
          "type": "string",
          "enum": [
            "covered",
            "deferred",
            "behavioral_delta",
            "not_applicable"
          ],
          "description": "Applicability disposition reused from project-invariant coverage (#3425 / #1492). snake_case."
        },
        "reason": {
          "type": "string",
          "description": "Required nonblank rationale when disposition is not_applicable."
        },
        "dispositionReason": {
          "type": "string",
          "description": "Alias for reason (not_applicable rationale)."
        },
        "stateSurfaces": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/StateSurface"
          }
        },
        "referenceApplications": {
          "type": "array"
        },
        "referenceApplicationComparisons": {
          "type": "array"
        }
      },
      "additionalProperties": true
    },
    "StateSurface": {
      "type": "object",
      "required": [
        "name",
        "classification"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "classification": {
          "type": "string",
          "enum": [
            "durable_product_state",
            "auth_session_state",
            "authorization_state",
            "audit_event_state",
            "external_integration_state",
            "canonical_artifact",
            "cache",
            "projection",
            "import_export_artifact",
            "dev_only_fixture",
            "ephemeral_ui_state"
          ]
        },
        "owner": {},
        "approvedStorage": {},
        "forbiddenStorage": {},
        "migrationRequired": {},
        "auditRequired": {},
        "concurrencyRequired": {},
        "permissionBoundary": {},
        "concurrencySemantics": {},
        "transactionBoundary": {},
        "recoverySemantics": {},
        "conflictDetection": {},
        "deleteSemantics": {},
        "migrationPath": {},
        "invalidationRules": {},
        "sourceOfTruth": {},
        "liveState": {},
        "authoritative": {},
        "mutable": {},
        "productionGuard": {}
      },
      "additionalProperties": true
    }
  }
}