openapi: 3.1.0
info:
  title: UI Surface Enforcement & Review Guardrails
  version: 1.0.0
  description: |
    Logical contract for the repository-owned guardrail workflow introduced by Spec 201.
    It documents authoring, review, repository-signal, test-guardrail, and exception
    semantics. It is not a public HTTP API.
servers:
  - url: https://tenantpilot.local/logical
paths:
  /logical/ui-guardrails/spec-impact/validate:
    post:
      summary: Validate one spec-level UI guardrail impact block
      operationId: validateSpecGuardrailImpact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecImpactValidationRequest'
      responses:
        '200':
          description: Spec guardrail impact evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecImpactValidationResult'
  /logical/ui-guardrails/reviews/classify:
    post:
      summary: Classify one UI or surface change through the reviewer checklist
      operationId: classifyReviewOutcome
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewClassificationRequest'
      responses:
        '200':
          description: Review classification returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewClassificationResult'
  /logical/ui-guardrails/repository-signals/assess:
    post:
      summary: Assess repository-level technical signals for a change
      operationId: assessRepositorySignals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepositorySignalAssessmentRequest'
      responses:
        '200':
          description: Repository-signal assessment returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositorySignalAssessmentResult'
  /logical/ui-guardrails/test-guardrails/resolve:
    post:
      summary: Resolve the required test profile for a surface contract class
      operationId: resolveTestGuardrailProfile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestGuardrailResolutionRequest'
      responses:
        '200':
          description: Test guardrail profile returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestGuardrailResolutionResult'
  /logical/ui-guardrails/exceptions/assess:
    post:
      summary: Assess whether an exception record is complete and bounded
      operationId: assessExceptionWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExceptionAssessmentRequest'
      responses:
        '200':
          description: Exception assessment returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionAssessmentResult'
  /logical/ui-guardrails/closeout/prepare:
    post:
      summary: Prepare the active feature PR close-out entry for guarded work
      operationId: prepareCloseoutEntry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseoutPreparationRequest'
      responses:
        '200':
          description: Close-out entry requirements returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloseoutPreparationResult'
  /logical/ui-guardrails/guidance:
    get:
      summary: Read the current guardrail guidance pack
      operationId: readGuardrailGuidance
      responses:
        '200':
          description: Guardrail guidance returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardrailGuidancePack'
components:
  schemas:
    SpecImpactValidationRequest:
      type: object
      additionalProperties: false
      required:
        - specPath
        - uiSurfaceChange
        - nativeCustomClassification
        - stateLayers
        - sharedFamilyRelevance
        - exceptionNeeded
      properties:
        specPath:
          type: string
        uiSurfaceChange:
          type: boolean
        nativeCustomClassification:
          type: string
        stateLayers:
          type: array
          items:
            type: string
            enum:
              - shell
              - page
              - detail
        sharedFamilyRelevance:
          type: string
        exceptionNeeded:
          type: boolean
        plannedGuardrailClasses:
          type: array
          items:
            type: string
        closeoutEntryTarget:
          type: string
    SpecImpactValidationResult:
      type: object
      additionalProperties: false
      required:
        - status
        - findings
        - closeoutEntryTarget
      properties:
        status:
          type: string
          enum:
            - complete
            - needs-revision
        findings:
          type: array
          items:
            type: string
        reviewerHandOff:
          type: string
        closeoutEntryTarget:
          type: string
    ReviewClassificationRequest:
      type: object
      additionalProperties: false
      required:
        - changeRef
        - triggeredMappings
        - checklistAnswers
      properties:
        changeRef:
          type: string
        triggeredMappings:
          type: array
          items:
            type: string
        checklistAnswers:
          type: array
          items:
            type: string
        exceptionClaimed:
          type: boolean
        closeoutEntryTarget:
          type: string
    ReviewClassificationResult:
      type: object
      additionalProperties: false
      required:
        - outcomeClass
        - workflowOutcome
        - recordLocation
      properties:
        outcomeClass:
          type: string
          enum:
            - blocker
            - strong-warning
            - documentation-required-exception
            - acceptable-special-case
        workflowOutcome:
          type: string
          enum:
            - keep
            - split
            - document-in-feature
            - follow-up-spec
            - reject-or-split
        missingEvidence:
          type: array
          items:
            type: string
        recordLocation:
          type: string
    RepositorySignalAssessmentRequest:
      type: object
      additionalProperties: false
      required:
        - changeRef
        - signalIds
      properties:
        changeRef:
          type: string
        signalIds:
          type: array
          items:
            type: string
        exceptionClaimed:
          type: boolean
        scopeNote:
          type: string
    RepositorySignalAssessmentResult:
      type: object
      additionalProperties: false
      required:
        - status
        - handlingModes
        - closeoutEntryRequired
      properties:
        status:
          type: string
          enum:
            - complete
            - needs-review
        handlingModes:
          type: array
          items:
            type: string
        requiresException:
          type: boolean
        closeoutEntryRequired:
          type: boolean
        notes:
          type: array
          items:
            type: string
    TestGuardrailResolutionRequest:
      type: object
      additionalProperties: false
      required:
        - surfaceClass
      properties:
        surfaceClass:
          type: string
          enum:
            - shared-detail-family
            - monitoring-state-page
            - global-context-shell
            - exception-coded-surface
            - standard-native-filament
        changedContractAreas:
          type: array
          items:
            type: string
        exceptionType:
          type: string
    TestGuardrailResolutionResult:
      type: object
      additionalProperties: false
      required:
        - requiredTestTypes
        - specialCoverageRequired
        - profileId
      properties:
        profileId:
          type: string
        requiredTestTypes:
          type: array
          items:
            type: string
        manualSmokeExpectations:
          type: array
          items:
            type: string
        specialCoverageRequired:
          type: boolean
    ExceptionAssessmentRequest:
      type: object
      additionalProperties: false
      required:
        - changeRef
        - exceptionType
        - brokenRules
        - boundaryPlan
        - closeoutEntryTarget
      properties:
        changeRef:
          type: string
        exceptionType:
          type: string
        brokenRules:
          type: array
          items:
            type: string
        productReason:
          type: string
        boundaryPlan:
          type: array
          items:
            type: string
        standardizationPlan:
          type: array
          items:
            type: string
        closeoutEntryTarget:
          type: string
    ExceptionAssessmentResult:
      type: object
      additionalProperties: false
      required:
        - status
        - spreadAllowed
        - closeoutEntryRequired
      properties:
        status:
          type: string
          enum:
            - complete
            - needs-revision
        spreadAllowed:
          type: boolean
        closeoutEntryRequired:
          type: boolean
        closeoutNotes:
          type: array
          items:
            type: string
    CloseoutPreparationRequest:
      type: object
      additionalProperties: false
      required:
        - changeRef
        - outcomeClass
        - handlingModes
        - workflowOutcome
      properties:
        changeRef:
          type: string
        outcomeClass:
          type: string
          enum:
            - blocker
            - strong-warning
            - documentation-required-exception
            - acceptable-special-case
        handlingModes:
          type: array
          items:
            type: string
        workflowOutcome:
          type: string
          enum:
            - keep
            - split
            - document-in-feature
            - follow-up-spec
            - reject-or-split
        proofDepth:
          type: array
          items:
            type: string
        duplicatePromptNotes:
          type: array
          items:
            type: string
    CloseoutPreparationResult:
      type: object
      additionalProperties: false
      required:
        - entryName
        - requiredFields
      properties:
        entryName:
          type: string
        requiredFields:
          type: array
          items:
            type: string
        lowImpactAllowed:
          type: boolean
        notes:
          type: array
          items:
            type: string
    GuardrailGuidancePack:
      type: object
      additionalProperties: false
      required:
        - entryPoints
        - outcomeClasses
        - workflowOutcomes
        - closeoutEntryName
      properties:
        entryPoints:
          type: array
          items:
            type: string
        outcomeClasses:
          type: array
          items:
            type: string
        workflowOutcomes:
          type: array
          items:
            type: string
        closeoutEntryName:
          type: string
        notes:
          type: array
          items:
            type: string