openapi: 3.0.3
info:
  title: TenantPilot Repo Governance - Cross-Domain Indicator Semantics Audit (Conceptual)
  version: 0.1.0
  description: |
    Conceptual contract for the repository-governance outputs produced by the
    cross-domain indicator semantics audit package.

    NOTE: These are planning and documentation artifacts inside the spec package,
    not application runtime endpoints. The paths below model the logical bundle
    shape that later reviewers and follow-up specs consume.
paths:
  /repository-governance/cross-domain-indicator-semantics/inventory:
    get:
      summary: Review the indicator inventory bundle
      description: |
        Logical artifact containing one entry per current indicator-like cue in
        the bounded repo scope. Each entry records the source seam, visible cue,
        semantic category, misunderstanding risk, and one bounded disposition.
      responses:
        '200':
          description: Indicator inventory bundle available for review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndicatorInventoryBundle'
      x-repository-artifact: true
  /repository-governance/cross-domain-indicator-semantics/standards-delta:
    get:
      summary: Review the derived standards delta
      description: |
        Logical artifact describing the standards guidance that should later be
        applied to docs/ui/tenantpilot-enterprise-ui-standards.md without
        turning this audit package into a runtime implementation pass.
      responses:
        '200':
          description: Standards-delta bundle available for review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardsDeltaBundle'
      x-repository-artifact: true
  /repository-governance/cross-domain-indicator-semantics/follow-up-map:
    get:
      summary: Review the bounded follow-up map
      description: |
        Logical artifact mapping ambiguous or risky cues to explicit later lanes.
        V1 lanes are separated intentionally so the audit package does not imply
        one broad runtime rewrite.
      responses:
        '200':
          description: Follow-up map bundle available for review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FollowUpMapBundle'
      x-repository-artifact: true
components:
  schemas:
    IndicatorInventoryBundle:
      type: object
      required:
        - review_scope
        - entries
        - related_spec_guardrails
      properties:
        review_scope:
          type: object
          required:
            - package
            - standards_target
            - bounded_domains
          properties:
            package:
              type: string
              example: specs/278-cross-domain-indicator-audit
            standards_target:
              type: string
              example: docs/ui/tenantpilot-enterprise-ui-standards.md
            bounded_domains:
              type: array
              items:
                type: string
        entries:
          type: array
          items:
            $ref: '#/components/schemas/IndicatorInventoryEntry'
        related_spec_guardrails:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSpecGuardrail'
    IndicatorInventoryEntry:
      type: object
      required:
        - entry_id
        - source_anchor
        - surface
        - domain
        - visible_cue
        - visual_pattern
        - data_source
        - calculation_basis
        - semantic_category
        - determinism
        - scope_mode
        - likely_user_reading
        - misunderstanding_risk
        - disposition
      properties:
        entry_id:
          type: string
        source_anchor:
          $ref: '#/components/schemas/IndicatorSourceAnchor'
        surface:
          type: string
        domain:
          type: string
        visible_cue:
          type: string
        visual_pattern:
          type: string
        data_source:
          type: string
        calculation_basis:
          type: string
        semantic_category:
          type: string
          enum:
            - execution progress
            - activity state
            - coverage
            - completion
            - health
            - readiness
            - risk
            - pressure
            - usage
            - capacity
            - score
            - generation state
            - unknown/ambiguous
        determinism:
          type: string
          enum:
            - determinate
            - indeterminate
            - unknown
        scope_mode:
          type: string
          enum:
            - tenant-prefiltered
            - tenantless-aggregate
            - workspace-aggregate
            - supporting-context
        audience_mode:
          type: string
          nullable: true
          enum:
            - customer-readable
            - operator-msp
            - support-platform
            - mixed
            - not-applicable
        likely_user_reading:
          type: string
        misunderstanding_risk:
          type: string
        disposition:
          type: string
          enum:
            - keep as-is
            - copy-only clarification
            - standards clarification
            - product decision
            - contract follow-up
            - shared-component follow-up
            - migration follow-up
            - defer
        follow_up_lane:
          type: string
          nullable: true
          enum:
            - standards patch lane
            - metric/indicator contract foundation
            - shared indicator component system
            - quality gate lane
            - domain migration lane
        related_guardrails:
          type: array
          items:
            type: string
        notes:
          type: string
          nullable: true
    IndicatorSourceAnchor:
      type: object
      required:
        - repo_path
        - source_type
        - surface_name
        - domain
      properties:
        repo_path:
          type: string
        source_type:
          type: string
          enum:
            - standard
            - spec
            - presenter
            - widget
            - service
            - builder
            - blade
            - other-code
        surface_name:
          type: string
        domain:
          type: string
        route_context:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
    StandardsDeltaBundle:
      type: object
      required:
        - target_doc
        - rules
      properties:
        target_doc:
          type: string
          example: docs/ui/tenantpilot-enterprise-ui-standards.md
        rules:
          type: array
          items:
            $ref: '#/components/schemas/StandardsDeltaRule'
    StandardsDeltaRule:
      type: object
      required:
        - rule_id
        - area
        - current_gap
        - proposed_guidance
        - target_doc
      properties:
        rule_id:
          type: string
        area:
          type: string
          enum:
            - allowed-categories
            - determinate-progress
            - freshness
            - wording
            - dashboard
            - anti-pattern
            - provider-boundary
        current_gap:
          type: string
        proposed_guidance:
          type: string
        target_doc:
          type: string
        follow_up_lane:
          type: string
          nullable: true
          enum:
            - standards patch lane
            - metric/indicator contract foundation
            - shared indicator component system
            - quality gate lane
            - domain migration lane
    FollowUpMapBundle:
      type: object
      required:
        - lanes
      properties:
        lanes:
          type: array
          items:
            $ref: '#/components/schemas/FollowUpLane'
    FollowUpLane:
      type: object
      required:
        - lane
        - purpose
        - out_of_scope_for_this_slice
        - likely_repo_surfaces
      properties:
        lane:
          type: string
          enum:
            - standards patch lane
            - metric/indicator contract foundation
            - shared indicator component system
            - quality gate lane
            - domain migration lane
        purpose:
          type: string
        out_of_scope_for_this_slice:
          type: boolean
        trigger_cues:
          type: array
          items:
            type: string
        likely_repo_surfaces:
          type: array
          items:
            type: string
        seed_questions:
          type: array
          items:
            type: string
    RelatedSpecGuardrail:
      type: object
      required:
        - spec_id
        - relation
        - note
        - out_of_scope_for_this_slice
      properties:
        spec_id:
          type: string
        relation:
          type: string
          enum:
            - context-only
            - guardrail
            - follow-up dependency
        note:
          type: string
        out_of_scope_for_this_slice:
          type: boolean