openapi: 3.1.0
info:
  title: Test Authoring Constitution & Review Guardrails
  version: 1.0.0
  description: |
    Logical contract for the repository-owned authoring and review workflow
    introduced by Spec 212. This documents constitution, template, checklist,
    and escalation semantics. It is not a public HTTP API.
servers:
  - url: https://tenantatlas.local/logical
paths:
  /logical/test-governance/spec-impact/validate:
    post:
      summary: Validate one spec-level testing and lane impact block
      operationId: validateSpecImpactBlock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpecImpactValidationRequest'
      responses:
        '200':
          description: Spec impact block evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpecImpactValidationResult'
  /logical/test-governance/plan-impact/validate:
    post:
      summary: Validate one planning-time test-governance block
      operationId: validatePlanImpactBlock
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanImpactValidationRequest'
      responses:
        '200':
          description: Plan impact block evaluated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanImpactValidationResult'
  /logical/test-governance/tasks/checklist/evaluate:
    post:
      summary: Evaluate whether a task checklist keeps test-governance obligations visible
      operationId: evaluateTaskGovernanceChecklist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskChecklistEvaluationRequest'
      responses:
        '200':
          description: Task-level governance checklist evaluation returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskChecklistEvaluationResult'
  /logical/test-governance/reviews/escalation-assessment:
    post:
      summary: Assess whether a test change requires governance escalation
      operationId: assessReviewEscalation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EscalationAssessmentRequest'
      responses:
        '200':
          description: Escalation assessment returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationAssessmentResult'
  /logical/test-governance/guidance:
    get:
      summary: Read the contributor guidance pack for test authoring decisions
      operationId: readContributorGuidance
      responses:
        '200':
          description: Contributor guidance returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContributorGuidancePack'
components:
  schemas:
    SpecImpactValidationRequest:
      type: object
      additionalProperties: false
      required:
        - specPath
        - validationLanes
        - testFamilyImpact
        - heavySurfaceImpact
        - fixtureCostImpact
        - reviewValidationCommand
      properties:
        specPath:
          type: string
        validationLanes:
          oneOf:
            - type: string
              enum:
                - N/A
            - type: array
              items:
                type: string
                enum:
                  - fast-feedback
                  - confidence
                  - heavy-governance
                  - browser
                  - profiling
                  - junit
        testFamilyImpact:
          type: string
        heavySurfaceImpact:
          type: string
        fixtureCostImpact:
          type: string
        budgetTrendImpact:
          type: string
        reviewValidationCommand:
          type: string
        escalationNeeded:
          type: boolean
    SpecImpactValidationResult:
      type: object
      additionalProperties: false
      required:
        - status
        - findings
      properties:
        status:
          type: string
          enum:
            - complete
            - needs-revision
        findings:
          type: array
          items:
            type: string
        reviewerHandOff:
          type: string
    PlanImpactValidationRequest:
      type: object
      additionalProperties: false
      required:
        - planPath
        - changedTestTypes
        - helperFixtureImpact
        - laneReshapeImpact
        - closingValidation
      properties:
        planPath:
          type: string
        changedTestTypes:
          type: array
          items:
            type: string
        helperFixtureImpact:
          type: string
        laneReshapeImpact:
          type: string
        closingValidation:
          type: string
        driftDocumentationTarget:
          type: string
    PlanImpactValidationResult:
      type: object
      additionalProperties: false
      required:
        - status
        - findings
      properties:
        status:
          type: string
          enum:
            - complete
            - needs-revision
        findings:
          type: array
          items:
            type: string
        taskChecklistRequirements:
          type: array
          items:
            type: string
    TaskChecklistEvaluationRequest:
      type: object
      additionalProperties: false
      required:
        - checklistId
        - items
        - runtimeChange
      properties:
        checklistId:
          type: string
        items:
          type: array
          items:
            type: string
        runtimeChange:
          type: boolean
        evidenceTarget:
          type: string
    TaskChecklistEvaluationResult:
      type: object
      additionalProperties: false
      required:
        - status
        - missingCoverage
      properties:
        status:
          type: string
          enum:
            - complete
            - incomplete
        missingCoverage:
          type: array
          items:
            type: string
        notes:
          type: array
          items:
            type: string
    EscalationAssessmentRequest:
      type: object
      additionalProperties: false
      required:
        - changeRef
        - triggers
      properties:
        changeRef:
          type: string
        triggers:
          type: array
          items:
            type: string
            enum:
              - new-heavy-family
              - new-browser-coverage
              - material-lane-cost-shift
              - broad-filament-livewire-governance-surface
              - revived-expensive-default
              - budget-or-baseline-relevant-change
              - major-suite-reshaping
        contextNote:
          type: string
    EscalationAssessmentResult:
      type: object
      additionalProperties: false
      required:
        - outcome
        - reason
      properties:
        outcome:
          type: string
          enum:
            - none
            - document-in-feature
            - follow-up-spec
            - reject-or-split
        reason:
          type: string
        recordLocation:
          type:
            - string
            - 'null'
    ContributorGuidancePack:
      type: object
      additionalProperties: false
      required:
        - guidanceId
        - decisionPoints
        - entryPoints
        - sharedVocabulary
      properties:
        guidanceId:
          type: string
        decisionPoints:
          type: array
          items:
            type: string
        examplePatterns:
          type: array
          items:
            type: string
        entryPoints:
          type: array
          items:
            type: string
        sharedVocabulary:
          type: array
          items:
            type: string