{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tenantpilot.local/specs/201/guardrail-governance.schema.json",
  "title": "UI Surface Guardrail Governance Pack",
  "description": "Repository-owned contract for the review, repository-signal, test-guardrail, exception, and workflow-touchpoint artifacts introduced by Spec 201.",
  "type": "object",
  "additionalProperties": false,
	  "required": [
	    "schemaVersion",
	    "ruleMappings",
	    "reviewChecklist",
	    "repositorySignals",
	    "testGuardrails",
	    "exceptionWorkflow",
	    "workflowTouchpoints",
	    "validationScenarios",
	    "closeoutEntry"
	  ],
  "properties": {
    "schemaVersion": {
      "type": "string"
    },
    "ruleMappings": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/ruleMapping"
      }
    },
    "reviewChecklist": {
      "$ref": "#/$defs/reviewChecklist"
    },
    "repositorySignals": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/repositorySignal"
      }
    },
    "testGuardrails": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/testGuardrail"
      }
    },
    "exceptionWorkflow": {
      "$ref": "#/$defs/exceptionWorkflow"
    },
    "workflowTouchpoints": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/workflowTouchpoint"
      }
    },
	    "validationScenarios": {
	      "type": "array",
	      "minItems": 2,
	      "items": {
	        "$ref": "#/$defs/validationScenario"
	      }
	    },
	    "closeoutEntry": {
	      "$ref": "#/$defs/closeoutEntry"
	    }
	  },
  "$defs": {
    "ruleMapping": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "mappingId",
	        "sourceRuleId",
	        "problemClass",
	        "operationalClasses",
	        "handlingMode",
	        "representativeCases",
	        "targetWorkflowSurfaces"
	      ],
      "properties": {
        "mappingId": { "type": "string" },
        "sourceRuleId": { "type": "string" },
        "problemClass": { "type": "string" },
        "operationalClasses": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "enum": [
              "review",
              "repository-signal",
              "test-guardrail",
              "exception",
              "workflow-touchpoint"
            ]
          }
        },
        "handlingMode": {
          "type": "string",
          "enum": [
            "hard-stop-candidate",
            "review-mandatory",
            "exception-required",
            "report-only"
          ]
        },
        "representativeCases": {
          "type": "array",
          "items": { "type": "string" }
        },
        "targetWorkflowSurfaces": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string" }
        },
        "deferredAutomation": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "reviewChecklist": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "checklistId",
        "questions",
        "outcomeClasses",
        "workflowOutcomes",
        "maxReviewMinutes"
      ],
      "properties": {
        "checklistId": { "type": "string" },
        "questions": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/reviewQuestion" }
        },
        "outcomeClasses": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "blocker",
              "strong-warning",
              "documentation-required-exception",
              "acceptable-special-case"
            ]
          }
        },
        "workflowOutcomes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "keep",
              "split",
              "document-in-feature",
              "follow-up-spec",
              "reject-or-split"
            ]
          }
        },
        "maxReviewMinutes": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "reviewQuestion": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "questionId",
	        "category",
	        "prompt",
	        "appliesWhen",
	        "linkedMappings",
	        "evidenceExpected",
	        "defaultOutcomeClass"
	      ],
      "properties": {
        "questionId": { "type": "string" },
        "category": {
          "type": "string",
          "enum": [
            "surface-classification",
            "native-usage",
            "shared-family",
            "state-layer",
            "exception",
            "test-coverage"
          ]
	        },
	        "prompt": { "type": "string" },
	        "appliesWhen": { "type": "string" },
	        "linkedMappings": {
	          "type": "array",
	          "minItems": 1,
	          "items": { "type": "string" }
	        },
	        "evidenceExpected": { "type": "string" },
	        "defaultOutcomeClass": {
	          "type": "string",
	          "enum": [
            "blocker",
            "strong-warning",
            "documentation-required-exception",
            "acceptable-special-case"
          ]
        }
      }
    },
    "repositorySignal": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "signalId",
	        "label",
	        "patternType",
	        "confidenceLevel",
	        "handlingMode",
	        "exceptionPath",
	        "futurePromotion"
	      ],
      "properties": {
        "signalId": { "type": "string" },
        "label": { "type": "string" },
        "patternType": {
          "type": "string",
          "enum": ["grep", "search", "path-pattern", "manual"]
        },
        "searchScopePaths": {
          "type": "array",
          "items": { "type": "string" }
        },
        "triggerExamples": {
          "type": "array",
          "items": { "type": "string" }
        },
        "confidenceLevel": {
          "type": "string",
          "enum": ["high", "medium", "low"]
        },
        "handlingMode": {
          "type": "string",
          "enum": [
            "report-only",
            "review-mandatory",
            "exception-required",
            "hard-stop-candidate"
          ]
        },
        "exceptionPath": { "type": "string" },
        "futurePromotion": { "type": "string" }
      }
    },
    "testGuardrail": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "profileId",
	        "surfaceClass",
	        "triggers",
	        "requiredTestTypes",
	        "manualSmokeExpectations",
	        "standardCoverageRule",
	        "exceptionHandlingRule"
	      ],
      "properties": {
        "profileId": { "type": "string" },
        "surfaceClass": {
          "type": "string",
          "enum": [
            "shared-detail-family",
            "monitoring-state-page",
            "global-context-shell",
            "exception-coded-surface",
            "standard-native-filament"
          ]
        },
        "triggers": {
          "type": "array",
          "items": { "type": "string" }
        },
        "requiredTestTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "functional-core",
              "state-contract",
              "exception-fallback",
              "manual-smoke"
            ]
          }
        },
        "manualSmokeExpectations": {
          "type": "array",
          "items": { "type": "string" }
        },
        "standardCoverageRule": { "type": "string" },
        "exceptionHandlingRule": { "type": "string" }
      }
    },
    "exceptionWorkflow": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "workflowId",
	        "supportedExceptionTypes",
	        "requiredFields",
	        "boundaryChecks",
	        "standardizationFields",
	        "spreadReviewRule",
	        "closeoutRequirement",
	        "closeoutNoteTarget"
	      ],
      "properties": {
        "workflowId": { "type": "string" },
        "supportedExceptionTypes": {
          "type": "array",
          "items": { "type": "string" }
        },
	        "requiredFields": {
	          "type": "array",
	          "items": { "type": "string" }
	        },
	        "boundaryChecks": {
	          "type": "array",
	          "items": { "type": "string" }
	        },
	        "standardizationFields": {
	          "type": "array",
	          "items": { "type": "string" }
	        },
	        "spreadReviewRule": { "type": "string" },
	        "closeoutRequirement": { "type": "string" },
	        "closeoutNoteTarget": { "type": "string" }
	      }
	    },
    "workflowTouchpoint": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "touchpointId",
	        "artifactPath",
	        "phase",
	        "requiredPrompts",
	        "linkedMappings",
	        "outcomeTarget"
	      ],
      "properties": {
        "touchpointId": { "type": "string" },
        "artifactPath": { "type": "string" },
        "phase": {
          "type": "string",
          "enum": ["spec", "plan", "tasks", "review", "closeout", "follow-up"]
        },
        "requiredPrompts": {
          "type": "array",
          "items": { "type": "string" }
        },
        "linkedMappings": {
          "type": "array",
          "items": { "type": "string" }
        },
        "outcomeTarget": { "type": "string" }
      }
    },
    "validationScenario": {
      "type": "object",
      "additionalProperties": false,
	      "required": [
	        "scenarioId",
	        "scenarioType",
	        "representativeArtifact",
	        "expectedMappings",
	        "expectedOutcomeClass",
	        "expectedWorkflowOutcome",
	        "status",
	        "notes"
	      ],
      "properties": {
        "scenarioId": { "type": "string" },
        "scenarioType": {
          "type": "string",
          "enum": [
            "low-impact",
            "fake-native",
            "shared-family",
            "state-layer",
            "legitimate-exception"
          ]
        },
        "representativeArtifact": { "type": "string" },
        "expectedMappings": {
          "type": "array",
          "items": { "type": "string" }
        },
        "expectedOutcomeClass": {
          "type": "string",
          "enum": [
            "blocker",
            "strong-warning",
            "documentation-required-exception",
            "acceptable-special-case"
          ]
        },
        "expectedWorkflowOutcome": {
          "type": "string",
          "enum": [
            "keep",
            "split",
            "document-in-feature",
            "follow-up-spec",
            "reject-or-split"
          ]
        },
        "status": {
          "type": "string",
          "enum": ["planned", "validated", "needs-tuning"]
        },
	        "notes": { "type": "string" }
	      }
	    },
	    "closeoutEntry": {
	      "type": "object",
	      "additionalProperties": false,
	      "required": [
	        "entryName",
	        "requiredFields",
	        "noteOwner",
	        "lowImpactRule",
	        "deferredAutomationField"
	      ],
	      "properties": {
	        "entryName": { "type": "string" },
	        "requiredFields": {
	          "type": "array",
	          "minItems": 1,
	          "items": { "type": "string" }
	        },
	        "noteOwner": { "type": "string" },
	        "lowImpactRule": { "type": "string" },
	        "deferredAutomationField": { "type": "string" }
	      }
	    }
	  }
	}