openapi: 3.0.3
info:
  title: Shoehorn Governance API
  description: Governance actions, dashboard metrics, and documentation health.
  version: 1.0.0

servers:
  - url: https://shoehorn.example.com/api/v1
    description: Production

paths:
  /governance/dashboard:
    get:
      summary: Get governance dashboard
      description: Returns aggregate metrics for governance actions across all entities.
      tags: [Governance]
      responses:
        '200':
          description: Dashboard metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_actions: { type: integer }
                  by_status:
                    type: object
                    properties:
                      open: { type: integer }
                      in_progress: { type: integer }
                      resolved: { type: integer }
                      dismissed: { type: integer }
                      wont_fix: { type: integer }
                  by_priority:
                    type: object
                    properties:
                      critical: { type: integer }
                      high: { type: integer }
                      medium: { type: integer }
                      low: { type: integer }

  /governance/documentation:
    get:
      summary: Get documentation health
      description: Returns documentation coverage and freshness metrics.
      tags: [Governance]
      responses:
        '200':
          description: Documentation health metrics

  /governance/actions:
    get:
      summary: List governance actions
      tags: [Governance Actions]
      parameters:
        - name: status
          in: query
          schema: { type: string, enum: [open, in_progress, resolved, dismissed, wont_fix] }
        - name: priority
          in: query
          schema: { type: string, enum: [critical, high, medium, low] }
        - name: type
          in: query
          schema: { type: string }
        - name: entity_id
          in: query
          schema: { type: string }
        - name: assigned_to
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 20 }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Paginated governance actions
          content:
            application/json:
              schema:
                type: object
                properties:
                  actions:
                    type: array
                    items: { $ref: '#/components/schemas/GovernanceAction' }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      nextCursor: { type: string }

    post:
      summary: Create governance action
      tags: [Governance Actions]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateActionRequest' }
      responses:
        '201':
          description: Action created

  /governance/actions/{id}:
    get:
      summary: Get governance action
      tags: [Governance Actions]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Action details

    patch:
      summary: Update governance action
      description: Update status, priority, assignee, or add notes.
      tags: [Governance Actions]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateActionRequest' }
      responses:
        '200':
          description: Action updated

    delete:
      summary: Delete governance action (soft delete)
      tags: [Governance Actions]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '204':
          description: Action deleted

components:
  schemas:
    GovernanceAction:
      type: object
      properties:
        id: { type: string, format: uuid }
        title: { type: string }
        description: { type: string }
        type: { type: string }
        status: { type: string, enum: [open, in_progress, resolved, dismissed, wont_fix] }
        priority: { type: string, enum: [critical, high, medium, low] }
        entity_id: { type: string }
        entity_name: { type: string }
        assigned_to: { type: string }
        created_by: { type: string }
        due_date: { type: string, format: date }
        resolution_notes: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    CreateActionRequest:
      type: object
      required: [title, type, priority]
      properties:
        title: { type: string }
        description: { type: string }
        type: { type: string }
        priority: { type: string, enum: [critical, high, medium, low] }
        entity_id: { type: string }
        assigned_to: { type: string }
        due_date: { type: string, format: date }

    UpdateActionRequest:
      type: object
      properties:
        status: { type: string, enum: [open, in_progress, resolved, dismissed, wont_fix] }
        priority: { type: string, enum: [critical, high, medium, low] }
        assigned_to: { type: string }
        resolution_notes: { type: string }
        due_date: { type: string, format: date }
