{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://gxp.md/schema/v2.json",
  "title": "GxP.MD v2 Frontmatter Schema",
  "description": "JSON Schema for validating GxP.MD v2.x frontmatter — annotation-first compliance instructions for AI coding agents in regulated industries",
  "type": "object",
  "required": [
    "gxpmd_version",
    "project",
    "regulatory",
    "risk",
    "annotations",
    "artifacts",
    "gates",
    "alcoa",
    "evidence"
  ],
  "additionalProperties": false,
  "properties": {
    "gxpmd_version": {
      "type": "string",
      "description": "GxP.MD specification version (semantic versioning). Must be 2.x.x for this schema.",
      "pattern": "^2\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$",
      "examples": ["2.1.0"]
    },

    "project": {
      "type": "object",
      "description": "Project identification and metadata",
      "required": ["name", "id", "version", "owner"],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Human-readable product name",
          "minLength": 1,
          "examples": ["Nexus Validation Platform"]
        },
        "id": {
          "type": "string",
          "description": "Unique product identifier (slug format)",
          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
          "examples": ["nexus-validation-platform"]
        },
        "version": {
          "type": "string",
          "description": "Current semantic version (MAJOR.MINOR.PATCH)",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
          "examples": ["2.1.0"]
        },
        "owner": {
          "type": "string",
          "description": "Quality-responsible individual or team",
          "minLength": 1,
          "examples": ["PharmaLedger Association"]
        },
        "contact": {
          "type": "string",
          "description": "Email or distribution list for quality issues",
          "format": "email",
          "examples": ["james@pharmaledger.org"]
        }
      }
    },

    "regulatory": {
      "type": "object",
      "description": "Regulatory framework and compliance requirements",
      "required": ["profile"],
      "additionalProperties": false,
      "properties": {
        "profile": {
          "type": "string",
          "description": "Pre-built regulatory profile to apply",
          "enum": [
            "pharma-standard",
            "medical-device",
            "clinical-trial",
            "laboratory",
            "custom"
          ],
          "examples": ["pharma-standard"]
        },
        "jurisdictions": {
          "type": "array",
          "description": "Regulatory jurisdictions that apply",
          "items": {
            "type": "string",
            "enum": [
              "FDA", "EMA", "PMDA", "HC", "TGA",
              "MHRA", "ANVISA", "CFDA", "ICH", "WHO"
            ]
          },
          "minItems": 1,
          "uniqueItems": true,
          "examples": [["FDA", "EMA"]]
        },
        "frameworks": {
          "type": "array",
          "description": "Specific regulatory frameworks to comply with (free-text strings)",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1,
          "uniqueItems": true,
          "examples": [["21 CFR Part 11", "EU Annex 11", "GAMP 5"]]
        },
        "gamp_category": {
          "type": ["string", "integer"],
          "description": "GAMP 5 software category classification",
          "enum": [1, 3, 4, 5, "1", "3", "4", "5"],
          "examples": [5]
        }
      }
    },

    "risk": {
      "type": "object",
      "description": "Risk classification and risk-based controls",
      "required": ["overall"],
      "additionalProperties": false,
      "properties": {
        "overall": {
          "type": "string",
          "description": "Overall project risk classification",
          "enum": ["LOW", "MEDIUM", "HIGH"],
          "examples": ["HIGH"]
        },
        "matrix": {
          "type": "object",
          "description": "Per-level risk configuration matrix",
          "additionalProperties": false,
          "properties": {
            "HIGH": { "$ref": "#/definitions/riskLevelConfig" },
            "MEDIUM": { "$ref": "#/definitions/riskLevelConfig" },
            "LOW": { "$ref": "#/definitions/riskLevelConfig" }
          }
        }
      }
    },

    "annotations": {
      "type": "object",
      "description": "Annotation format and required tags for source and test files",
      "required": ["required_tags"],
      "additionalProperties": false,
      "properties": {
        "schema_version": {
          "type": "string",
          "description": "Annotation schema version",
          "examples": ["1.0"]
        },
        "required_tags": {
          "type": "object",
          "description": "Tags required on source and test files",
          "required": ["source", "test"],
          "additionalProperties": false,
          "properties": {
            "source": {
              "type": "array",
              "description": "Required annotation tags on source files implementing GxP functionality",
              "items": {
                "type": "string",
                "enum": ["@gxp-req", "@gxp-spec", "@gxp-risk"]
              },
              "minItems": 1,
              "uniqueItems": true,
              "examples": [["@gxp-req", "@gxp-spec", "@gxp-risk"]]
            },
            "test": {
              "type": "array",
              "description": "Required annotation tags on test files",
              "items": {
                "type": "string",
                "enum": ["@gxp-spec", "@trace", "@test-type", "@gxp-risk"]
              },
              "minItems": 1,
              "uniqueItems": true,
              "examples": [["@gxp-spec", "@trace", "@test-type", "@gxp-risk"]]
            }
          }
        },
        "format": {
          "type": "string",
          "description": "Annotation format in source code",
          "enum": ["block_comment", "decorator", "companion_file"],
          "default": "block_comment",
          "examples": ["block_comment"]
        }
      }
    },

    "artifacts": {
      "type": "object",
      "description": "Artifact generation and management configuration",
      "required": ["directory"],
      "additionalProperties": false,
      "properties": {
        "directory": {
          "type": "string",
          "description": "Directory path for artifact storage (relative to project root)",
          "pattern": "^[^\\0]+$",
          "examples": [".gxp"]
        },
        "engine": {
          "type": "string",
          "description": "Artifact engine: rosie (ROSIE RFC-001 tooling), custom, or none (annotations only)",
          "enum": ["rosie", "custom", "none"],
          "default": "none",
          "examples": ["none"]
        },
        "formal_artifacts": {
          "type": "string",
          "description": "Whether formal REQ/US/SPEC markdown documents are required, optional, or disabled",
          "enum": ["required", "optional", "none"],
          "default": "optional",
          "examples": ["optional"]
        },
        "traceability_enforcement": {
          "type": "string",
          "description": "Level of traceability enforcement: strict (errors break gates), warn (warnings only), off (no enforcement)",
          "enum": ["strict", "warn", "off"],
          "default": "strict",
          "examples": ["strict"]
        }
      }
    },

    "gates": {
      "type": "object",
      "description": "Quality gate definitions. Each gate is a list of check names (strings) that must pass.",
      "required": ["pre_commit", "pre_merge", "per_release"],
      "additionalProperties": false,
      "properties": {
        "pre_commit": {
          "type": "array",
          "description": "Gates that run before each commit",
          "items": { "type": "string" },
          "examples": [["annotations_valid", "no_untagged_gxp_code"]]
        },
        "pre_merge": {
          "type": "array",
          "description": "Gates that run before merging to main branch",
          "items": { "type": "string" },
          "examples": [["all_tests_pass", "coverage_meets_threshold", "review_complete_if_required", "no_orphan_annotations"]]
        },
        "per_release": {
          "type": "array",
          "description": "Gates that run before production release (note: per_release, not pre_release)",
          "items": { "type": "string" },
          "examples": [["harden_sweep_complete", "traceability_matrix_current", "evidence_packages_complete", "compliance_status_generated", "risk_assessment_current"]]
        }
      }
    },

    "harden": {
      "type": "object",
      "description": "Harden mode configuration — periodic compliance formalization sweep",
      "additionalProperties": false,
      "properties": {
        "frequency": {
          "type": "string",
          "description": "How often harden mode runs",
          "enum": ["per_sprint", "per_release", "manual"],
          "default": "per_sprint",
          "examples": ["per_sprint"]
        },
        "outputs": {
          "type": "array",
          "description": "Artifacts produced by the harden sweep",
          "items": {
            "type": "string",
            "enum": [
              "traceability_matrix",
              "compliance_status_report",
              "evidence_packages",
              "gap_analysis"
            ]
          },
          "uniqueItems": true,
          "examples": [["traceability_matrix", "compliance_status_report", "evidence_packages", "gap_analysis"]]
        }
      }
    },

    "alcoa": {
      "type": "object",
      "description": "ALCOA+ data integrity principles enforcement. Each principle has an enforce boolean and a method string.",
      "additionalProperties": false,
      "properties": {
        "attributable": { "$ref": "#/definitions/alcoaPrinciple" },
        "legible": { "$ref": "#/definitions/alcoaPrinciple" },
        "contemporaneous": { "$ref": "#/definitions/alcoaPrinciple" },
        "original": { "$ref": "#/definitions/alcoaPrinciple" },
        "accurate": { "$ref": "#/definitions/alcoaPrinciple" }
      }
    },

    "evidence": {
      "type": "object",
      "description": "Evidence collection, signing, and retention configuration",
      "required": ["signing_algorithm"],
      "additionalProperties": false,
      "properties": {
        "capture": {
          "type": "string",
          "description": "How evidence is captured",
          "enum": ["ci_native", "agent_manual", "hybrid"],
          "default": "ci_native",
          "examples": ["ci_native"]
        },
        "retention_days": {
          "type": "integer",
          "description": "Evidence retention period in days",
          "minimum": 1,
          "examples": [90]
        },
        "signing_algorithm": {
          "type": "string",
          "description": "Cryptographic signing algorithm for evidence packages (JWS)",
          "const": "ES256",
          "examples": ["ES256"]
        },
        "state_hash": {
          "type": "object",
          "description": "System state hash configuration for evidence integrity",
          "additionalProperties": false,
          "properties": {
            "algorithm": {
              "type": "string",
              "description": "Hash algorithm",
              "enum": ["SHA-256", "SHA-384", "SHA-512"],
              "default": "SHA-256",
              "examples": ["SHA-256"]
            },
            "scope": {
              "type": "string",
              "description": "Root directory to hash",
              "examples": ["/src"]
            },
            "excludes": {
              "type": "array",
              "description": "Patterns to exclude from hashing",
              "items": { "type": "string" },
              "examples": [["node_modules", ".*", "*.log", "dist"]]
            }
          }
        }
      }
    },

    "agent": {
      "type": "object",
      "description": "AI agent behavioral mode",
      "additionalProperties": false,
      "properties": {
        "mode": {
          "type": "string",
          "description": "Agent operation mode: strict (all rules are MUST), risk_proportionate (rules scale with risk level), advisory (guidance only, no enforcement)",
          "enum": ["strict", "risk_proportionate", "advisory"],
          "default": "risk_proportionate",
          "examples": ["risk_proportionate"]
        }
      }
    },

    "metadata": {
      "type": "object",
      "description": "Additional metadata and custom fields",
      "additionalProperties": true
    }
  },

  "definitions": {
    "riskLevelConfig": {
      "type": "object",
      "description": "Configuration for a specific risk level",
      "required": ["coverage_threshold", "required_tiers"],
      "additionalProperties": false,
      "properties": {
        "coverage_threshold": {
          "type": "integer",
          "description": "Minimum test coverage percentage required",
          "minimum": 0,
          "maximum": 100,
          "examples": [95]
        },
        "required_tiers": {
          "type": "array",
          "description": "Required qualification tiers (IQ/OQ/PQ)",
          "items": {
            "type": "string",
            "enum": ["IQ", "OQ", "PQ"]
          },
          "minItems": 1,
          "uniqueItems": true,
          "examples": [["IQ", "OQ", "PQ"]]
        },
        "signing_required": {
          "type": "boolean",
          "description": "Whether JWS signing is required for evidence at this risk level",
          "examples": [false]
        },
        "review_required": {
          "type": "boolean",
          "description": "Whether peer review is required before merge at this risk level",
          "examples": [true]
        }
      }
    },
    "alcoaPrinciple": {
      "type": "object",
      "description": "ALCOA+ principle enforcement — boolean enforce flag with implementation method",
      "required": ["enforce"],
      "additionalProperties": false,
      "properties": {
        "enforce": {
          "type": "boolean",
          "description": "Whether this ALCOA+ principle is enforced",
          "examples": [true]
        },
        "method": {
          "type": "string",
          "description": "Implementation method for enforcement",
          "examples": ["git_author", "markdown_lint", "commit_timestamp", "jws_signature", "system_state_hash"]
        }
      }
    }
  }
}