openapi.yaml

openapi: 3.0.3

info:
  title: Sinapse Service Contracts
  version: 0.1.0
  description: Contratos versionados entre backend, serviço de IA e automações n8n.

servers:
  - url: http://localhost:3001
    description: Backend Node.js
  - url: http://localhost:8000
    description: Serviço de IA local

paths:
  /api/v1/quality/configuration/definitions:
    get:
      summary: Consultar DoR e DoD da organização por nível
      tags: [Quality]
      security: [{bearerAuth: []}]
      responses:
        '200':
          description: Definições descritivas, versão, autor e data; listas inicialmente vazias
          content:
            application/json:
              schema:
                type: object
                properties:
                  version: {type: integer}
                  updated_by: {type: string, format: uuid, nullable: true}
                  updated_by_name: {type: string, nullable: true}
                  updated_at: {type: string, format: date-time}
                  levels: &workDefinitionLevels
                    type: object
                    additionalProperties: false
                    required: [epico, feature, pbi]
                    properties:
                      epico: &workDefinition
                        type: object
                        additionalProperties: false
                        required: [dor, dod]
                        properties:
                          dor: {type: array, maxItems: 50, uniqueItems: true, items: {type: string, minLength: 1, maxLength: 500, pattern: '^[^\r\n\u2028\u2029]*$'}}
                          dod: {type: array, maxItems: 50, uniqueItems: true, items: {type: string, minLength: 1, maxLength: 500, pattern: '^[^\r\n\u2028\u2029]*$'}}
                      feature: *workDefinition
                      pbi: *workDefinition
        '401': {description: Autenticação obrigatória}
    put:
      summary: Administrador atualiza DoR e DoD sem alterar as verificações automáticas
      tags: [Quality]
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [expected_version, levels]
              properties:
                expected_version: {type: integer, minimum: 1, maximum: 2147483646}
                levels: *workDefinitionLevels
      responses:
        '200': {description: Definições gravadas com versão incrementada, autor/data e auditoria; mesmo formato da consulta}
        '400': {description: Condições inválidas, duplicadas ou acima dos limites}
        '401': {description: Autenticação obrigatória}
        '403': {description: Somente administrador pode alterar}
        '409': {description: Versão desatualizada; recarregar antes de salvar}
  /api/v1/projects/{projectId}/index-events:
    parameters:
      - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
    get:
      summary: Lista os últimos 100 eventos de indexação do projeto
      operationId: listIndexEvents
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Estados, versões, tentativas e códigos seguros de falha, sem conteúdo da origem.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/IndexEvent'
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Projeto inexistente ou sem acesso}
  /api/v1/projects/{projectId}/index-events/{eventId}/reprocess:
    parameters:
      - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
      - {name: eventId, in: path, required: true, schema: {type: string, format: uuid}}
    post:
      summary: Reenfileira um evento de indexação (admin ou PO)
      operationId: reprocessIndexEvent
      description: Repetir enquanto pendente preserva a fila. Eventos substituídos retornam 404; reserva ativa ou projeto arquivado retorna 409.
      security: [{cookieAuth: []}]
      responses:
        '202':
          description: Evento pendente
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: {type: string, enum: [pendente]}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Sem permissão de escrita}
        '404': {description: Projeto ou evento inexistente ou sem acesso}
        '409': {description: Projeto arquivado ou evento em processamento}
  /api/v1/projects/{projectId}/documents/{documentId}/excerpts:
    parameters:
      - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
      - {name: documentId, in: path, required: true, schema: {type: string, format: uuid}}
    get:
      summary: Lê o texto indexado do documento na página do trecho selecionado
      operationId: readDocumentExcerpts
      security: [{cookieAuth: []}]
      parameters:
        - {name: chunk_id, in: query, required: true, schema: {type: string, format: uuid}}
        - {name: offset, in: query, schema: {type: integer, minimum: 0, maximum: 99999999}}
      responses:
        '200':
          description: Página de até 20 trechos em ordem de origem, sem embeddings.
          content:
            application/json:
              schema:
                type: object
                required: [document, items, offset, total, next_offset]
                properties:
                  document:
                    type: object
                    properties:
                      id: {type: string, format: uuid}
                      name: {type: string}
                      project_id: {type: string, format: uuid}
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id: {type: string, format: uuid}
                        text: {type: string}
                        index: {type: integer, minimum: 0}
                  offset: {type: integer, minimum: 0}
                  total: {type: integer, minimum: 0}
                  next_offset: {type: integer, nullable: true}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Documento ou trecho indisponível ou sem acesso ao projeto}
  /api/v1/admin/ai-harness/{mode}:
    parameters:
      - $ref: '#/components/parameters/HarnessMode'
    get:
      operationId: getHarnessConfiguration
      summary: Consulta a revisão vigente e os schemas do modo (somente admin)
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Revisão vigente; versão zero corresponde à configuração distribuída
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HarnessRevision'}
        '400': {description: Modo inválido}
        '401': {description: Autenticação necessária}
        '403': {description: Somente administrador}
    put:
      operationId: updateHarnessConfiguration
      summary: Publica uma nova revisão independente; próxima solicitação usa a mudança sem reinício
      security: [{cookieAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [expected_version, config]
              properties:
                expected_version: {type: integer, minimum: 0, maximum: 2147483646}
                config: {$ref: '#/components/schemas/HarnessConfig'}
      responses:
        '201':
          description: Revisão publicada e imediatamente vigente
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HarnessRevision'}
        '400': {description: Configuração ou modo inválido}
        '401': {description: Autenticação necessária}
        '403': {description: Somente administrador}
        '409': {description: Outra revisão foi publicada; recarregue antes de salvar}
  /api/v1/admin/ai-harness/{mode}/history:
    get:
      operationId: listHarnessHistory
      summary: Histórico imutável do modo, até 50 revisões por página
      security: [{cookieAuth: []}]
      parameters:
        - $ref: '#/components/parameters/HarnessMode'
        - in: query
          name: before
          schema: {type: integer, minimum: 1, maximum: 999999999}
      responses:
        '200':
          description: Histórico do mais recente para o mais antigo; next_before permite continuar
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: {$ref: '#/components/schemas/HarnessRevision'}
                  next_before: {type: integer, nullable: true}
        '400': {description: Modo ou cursor inválido}
        '401': {description: Autenticação necessária}
        '403': {description: Somente administrador}
  /api/v1/admin/projects/{id}/purge:
    post:
      operationId: purgeProjectContext
      summary: Expurgo transacional do contexto indexado do projeto (PBI-02.2.4 / S2-05)
      description: >
        Remove todo o conteúdo indexado (tabela chunk e fila de eventos) do projeto informado,
        exigindo a confirmação explícita do nome do projeto. Preserva intactos os demais projetos
        e registra auditoria da operação administrativa.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID do projeto a ser expurgado
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - confirmacao_nome
              properties:
                confirmacao_nome:
                  type: string
                  description: Digitação do nome exato do projeto para confirmar o expurgo
                justificativa:
                  type: string
                  description: Justificativa opcional da operação de expurgo
      responses:
        '200':
          description: Contexto do projeto expurgado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: sucesso
                  message:
                    type: string
                  projeto_id:
                    type: string
                    format: uuid
                  projeto_nome:
                    type: string
                  chunks_removidos:
                    type: integer
                  documentos_cancelados:
                    type: integer
                    description: Documentos tirados da fila e leases invalidados pelo expurgo
                  relatorios_cancelados:
                    type: integer
                    description: Relatórios com aprovação revogada e leases invalidados; exigem nova revisão humana
                  eventos_removidos:
                    type: integer
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Somente administrador
        '404':
          description: Projeto não encontrado
  /api/v1/projects/{projectId}/ai/requests:

    post:
      operationId: runHarness
      summary: Executa o harness local vigente sem gravar conteúdo do item
      description: >
        Exige admin ou PO e acesso ao projeto. Trechos de consulta/recomendação são recuperados
        pelo backend no projeto autorizado; não podem ser fornecidos pelo cliente. Levantamento
        aceita campos do nível e texto_livre. Consulta/recomendação aceitam pergunta. Combinações
        válidas são levantamento/questionar,padronizar,cenarios; consulta/responder; recomendacao/similares.
        Cenários detalhados são exclusivos de PBI e exigem a história completa (COMO UM, EU QUERO
        e PARA QUE); sem ela a resposta é 400 HISTORIA_INCOMPLETA e o modelo não é consultado.
        Cada cenário sugerido tem nome, tipo (caminho_principal, acesso_nao_autorizado ou alternativo),
        dado, quando e entao. Há sempre um caminho_principal e, quando a história ou as regras citam
        um termo de rules.permission_terms, também um acesso_nao_autorizado cujo entao descreve a recusa
        (verificação lexical; não valida a regra de permissão em si) (S2-11). Schemas JSON
        estritos por operação e nível estão disponíveis em getHarnessConfiguration. Qualquer falha
        de geração ou validação retorna 503.
      security: [{cookieAuth: []}]
      parameters:
        - in: path
          name: projectId
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [mode, operation]
              properties:
                mode: {type: string, enum: [levantamento, consulta, recomendacao]}
                operation: {type: string, enum: [questionar, padronizar, cenarios, responder, similares]}
                level: {type: string, enum: [epico, feature, pbi], default: pbi}
                fields:
                  type: object
                  maxProperties: 10
                  additionalProperties: {type: string, maxLength: 6000}
      responses:
        '200':
          description: Saída validada; nenhuma gravação no item e nenhum registro do prompt
          content:
            application/json:
              schema:
                type: object
                required: [mode, version, schema_version, operation, level, result]
                properties:
                  mode: {type: string, enum: [levantamento, consulta, recomendacao]}
                  version: {type: integer, minimum: 0}
                  schema_version: {type: integer, enum: [1]}
                  operation: {type: string}
                  level: {type: string, enum: [epico, feature, pbi]}
                  result: {type: object, description: Saída conforme o schema da operação/nível da revisão}
        '400':
          description: >
            Solicitação inválida. Em cenarios com história incompleta, code é HISTORIA_INCOMPLETA
            e details.campos lista os blocos vazios da história.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: {type: string}
                  code: {type: string, enum: [VALIDATION_ERROR, HISTORIA_INCOMPLETA]}
                  details:
                    type: object
                    properties:
                      campos:
                        type: array
                        items: {type: string, enum: [historia_como_um, historia_eu_quero, historia_para_que]}
        '401': {description: Autenticação necessária}
        '403': {description: Perfil sem permissão}
        '404': {description: Projeto inexistente ou sem acesso}
        '503': {description: IA indisponível ou saída rejeitada; edição preservada}

  /api/v1/projects/{projectId}/epicos:
    $ref: './epics-compat.yaml#/collection'
  /api/projects/{projectId}/epicos:
    $ref: './epics-compat.yaml#/collection'
  /api/v1/epicos/{id}:
    $ref: './epics-compat.yaml#/item'
  /api/epicos/{id}:
    $ref: './epics-compat.yaml#/item'
  /api/v1/epicos/{id}/complete:
    $ref: './epics-compat.yaml#/complete'
  /api/epicos/{id}/complete:
    $ref: './epics-compat.yaml#/complete'
  /health:
    get:
      summary: Verifica disponibilidade do serviço
      security: []
      responses:
        '200':
          description: Serviço saudável
        '503':
          description: Dependência indisponível

  /api/v1/auth/login:
    post:
      summary: Autentica um usuário e inicia uma sessão
      operationId: login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Autenticação realizada com sucesso
          headers:
            Set-Cookie:
              description: Cookie HttpOnly da sessão. Em produção também utiliza Secure.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          description: Credenciais inválidas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Usuário inativo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Limite de tentativas de autenticação excedido temporariamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/auth/logout:
    post:
      summary: Encerra e revoga a sessão atual
      operationId: logout
      security:
        - cookieAuth: []
      responses:
        '204':
          description: Sessão encerrada com sucesso
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/me:
    get:
      summary: Retorna o usuário autenticado
      operationId: getAuthenticatedUser
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Usuário da sessão atual
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthUserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/projects:
    post:
      summary: Cadastra um novo projeto (PBI-01.1.1 / S1-03)
      operationId: createProject
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: Projeto criado com sucesso com status ativo e auditoria registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Perfil sem permissão de escrita
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflito de nome duplicado entre projetos ativos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      summary: Lista projetos com paginação e busca (S1-03)
      operationId: listProjects
      security:
        - cookieAuth: []
      parameters:
        - name: status
          in: query
          required: false
          description: Ausente exclui arquivados; arquivado retorna somente arquivados; todos inclui todos os estados.
          schema:
            type: string
            enum: [ativo, em_andamento, concluido, arquivado, todos]
        - name: busca
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum: [created_at_desc, created_at_asc, nome_asc, nome_desc]
            default: created_at_desc
      responses:
        '200':
          description: Lista paginada de projetos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedProjectsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/projects/{id}:
    get:
      summary: Obtém detalhes de um projeto por ID (S1-03)
      operationId: getProjectById
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Detalhes do projeto com estatísticas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Atualiza dados de um projeto (S1-03 / S1-08)
      operationId: updateProject
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: Projeto atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Perfil sem permissão de escrita
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Nome duplicado ou tentativa de editar projeto arquivado (somente leitura).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    patch:
      summary: Atualiza dados de um projeto (S1-03 / S1-08) (parcial, mesmo corpo do PUT)
      operationId: updateProjectPartial
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '200':
          description: Projeto atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Perfil sem permissão de escrita
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Nome duplicado ou tentativa de editar projeto arquivado (somente leitura).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/projects/{id}/archive-impact:
    get:
      summary: Consulta quantidade de novos itens afetados pela cascata (S1-09)
      operationId: getProjectArchiveImpact
      description: Disponível para po e admin. Não modifica registros. Itens já arquivados não entram na contagem.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Contagens para confirmação explícita
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveImpact'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Projeto não encontrado

  /api/v1/projects/{id}/archive:
    patch:
      summary: Arquiva projeto, épicos, features e PBIs em cascata (S1-09)
      operationId: archiveProject
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirmado, impacto]
              properties:
                confirmado:
                  type: boolean
                  enum: [true]
                impacto:
                  $ref: '#/components/schemas/ArchiveImpact'
                justificativa:
                  type: string
                  maxLength: 2000
      responses:
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          description: Contagem mudou desde a prévia. Consultar novamente e pedir nova confirmação.
        '200':
          description: Cascata e auditoria confirmadas atomicamente. Repetição preserva as datas e não duplica auditoria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Perfil sem permissão de escrita
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/projects/{id}/backlog-tree:
    get:
      summary: Retorna a hierarquia do backlog e tecnologias associadas (S1-16)
      operationId: getProjectBacklogTree
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Árvore ordenada dentro de um snapshot consistente do banco
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectBacklogTreeResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado

  /api/v1/technologies:
    get:
      summary: Lista o catálogo de tecnologias para associação ao backlog
      operationId: listTechnologies
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Catálogo ordenado sem dados pessoais de desenvolvedores
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TechnologyOption'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/epics:
    post:
      summary: Cadastra um épico dentro de um projeto (PBI-01.1.2 / S1-05)
      operationId: createEpic
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. Bloqueia projeto arquivado ou inexistente.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEpicRequest'
      responses:
        '201':
          description: Épico criado com status rascunho
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Projeto não encontrado

    get:
      summary: Lista épicos de um projeto (S1-05)
      operationId: listEpics
      security:
        - cookieAuth: []
      parameters:
        - name: projeto_id
          in: query
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            type: string
            enum: [rascunho, concluido, ativo, arquivado, todos]
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Lista paginada de épicos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEpicsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/epics/{id}:
    get:
      summary: Obtém detalhes de um épico por ID (S1-05)
      operationId: getEpicById
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Detalhes do épico com estatísticas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Épico não encontrado

    put:
      summary: Atualiza dados de um épico (S1-05)
      operationId: updateEpic
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEpicRequest'
      responses:
        '200':
          description: Épico atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Épico não encontrado

    patch:
      summary: Atualiza dados de um épico (S1-05) (parcial, mesmo corpo do PUT)
      operationId: updateEpicPartial
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEpicRequest'
      responses:
        '200':
          description: Épico atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Épico não encontrado

  /api/v1/epics/{id}/complete:
    patch:
      summary: Marca um épico como concluído quando os campos obrigatórios do guia e ao menos um critério existirem (PBI-01.1.2 / S1-05)
      operationId: completeEpic
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Épico concluído
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpicResponse'
        '400':
          description: Campos obrigatórios ou critérios de aceitação ausentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Épico não encontrado

  /api/v1/features:
    post:
      summary: Cadastra uma feature dentro de um épico (PBI-01.1.3 / S1-06)
      operationId: createFeature
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeatureRequest'
      responses:
        '201':
          description: Feature criada com status rascunho
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Épico não encontrado

    get:
      summary: Lista features de um épico (S1-06)
      operationId: listFeatures
      security:
        - cookieAuth: []
      parameters:
        - name: epico_id
          in: query
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            type: string
            enum: [rascunho, concluido, arquivado, todos]
      responses:
        '200':
          description: Lista paginada de features
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFeaturesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/features/{id}:
    get:
      summary: Obtém detalhes de uma feature, incluindo o épico de origem (PBI-01.1.3 / S1-06)
      operationId: getFeatureById
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Detalhes da feature com contexto do épico
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
        '404':
          description: Feature não encontrada

    put:
      summary: Atualiza dados de uma feature (S1-06)
      operationId: updateFeature
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeatureRequest'
      responses:
        '200':
          description: Feature atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
        '404':
          description: Feature não encontrada

    patch:
      summary: Atualiza dados de uma feature (S1-06) (parcial, mesmo corpo do PUT)
      operationId: updateFeaturePartial
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeatureRequest'
      responses:
        '200':
          description: Feature atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
        '404':
          description: Feature não encontrada

  /api/v1/features/{id}/complete:
    patch:
      summary: Marca uma feature como concluída quando descrição e objetivo estiverem preenchidos (PBI-01.1.3 / S1-06)
      operationId: completeFeature
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Feature concluída
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
        '400':
          description: Campos obrigatórios ausentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Feature não encontrada

  /api/v1/pbis:
    post:
      summary: Cadastra um PBI com história em três blocos dentro de uma feature (PBI-01.1.4 / S1-07)
      operationId: createPbi
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. O código é gerado automaticamente pelo sistema.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePbiRequest'
      responses:
        '201':
          description: PBI criado com status rascunho e código provisório gerado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Feature não encontrada

    get:
      summary: Lista PBIs de uma feature (S1-07)
      operationId: listPbis
      security:
        - cookieAuth: []
      parameters:
        - name: feature_id
          in: query
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            type: string
            enum: [rascunho, concluido, arquivado, todos]
      responses:
        '200':
          description: Lista paginada de PBIs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPbisResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/pbis/{id}:
    get:
      summary: Obtém detalhes de um PBI, incluindo a cadeia feature/épico/projeto (PBI-01.1.4 / S1-07)
      operationId: getPbiById
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Detalhes do PBI com contexto hierárquico
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiResponse'
        '404':
          description: PBI não encontrado

    put:
      summary: Atualiza dados de um PBI (S1-07)
      operationId: updatePbi
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePbiRequest'
      responses:
        '200':
          description: PBI atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiResponse'
        '404':
          description: PBI não encontrado

    patch:
      summary: Atualiza dados de um PBI (S1-07) (parcial, mesmo corpo do PUT)
      operationId: updatePbiPartial
      description: Escrita permitida apenas aos perfis po e admin; dev recebe 403. PATCH no mesmo caminho é um alias desta operação.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePbiRequest'
      responses:
        '200':
          description: PBI atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiResponse'
        '404':
          description: PBI não encontrado

  /api/v1/pbis/{id}/complete:
    patch:
      summary: Marca um PBI como concluído quando ao menos um cenário DADO/QUANDO/ENTÃO existir e o título estiver no infinitivo (PBI-01.1.4, PBI-01.3.1 / S1-07, S1-13)
      operationId: completePbi
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: PBI concluído
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiResponse'
        '400':
          description: >-
            Nenhum cenário de aceitação registrado e/ou título fora do padrão de verbo no
            infinitivo. O campo `details.campos_faltantes` pode conter `cenarios_aceitacao`
            e/ou `titulo_infinitivo`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: PBI não encontrado

  /api/v1/pbis/{id}/quality:
    get:
      summary: Executa o motor determinístico de qualidade do PBI (título infinitivo, história e cenários, termos vagos) (PBI-01.3.1 a PBI-01.3.4 / S1-13)
      operationId: getPbiQuality
      description: >-
        Não bloqueia nada por si só — apenas relata. O bloqueio de conclusão real acontece em
        PATCH /pbis/{id}/complete.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Relatório de qualidade do PBI
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiQualityReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: PBI não encontrado

  /api/v1/pbis/{id}/relations:
    get:
      operationId: listPbiRelations
      summary: Listar relações bidirecionais do PBI (PBI-01.5.3 / S2-15)
      description: Lista dependências, similaridades e substituições conectadas ao PBI (como origem ou destino), retornando apenas itens de projetos acessíveis ao usuário autenticado.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Lista de relações do PBI
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PbiRelationView'
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: PBI não encontrado
    post:
      operationId: createPbiRelation
      summary: Criar relação entre PBIs com detecção de ciclo (PBI-01.5.3 / S2-15)
      description: Registra uma relação (depende_de, similar_a ou substitui) com outro PBI. Impede ciclos de dependência inclusive em solicitações simultâneas entre projetos. Itens ou ancestrais arquivados são somente leitura; relações repetidas retornam conflito.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pbi_destino_id
                - tipo_relacao
              properties:
                pbi_destino_id:
                  type: string
                  format: uuid
                  description: ID do PBI de destino da relação
                tipo_relacao:
                  type: string
                  enum: [depende_de, similar_a, substitui]
                  description: Tipo de relação entre os PBIs
      responses:
        '201':
          description: Relação criada com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiRelationView'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: PBI de origem ou destino não encontrado
        '409':
          description: Conflito de relação existente ou projeto arquivado

  /api/v1/pbis/{id}/relations/{relationId}:
    delete:
      operationId: deletePbiRelation
      summary: Remover relação de um PBI (PBI-01.5.3 / S2-15)
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: relationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Relação removida com sucesso
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Relação ou PBI não encontrado

  /api/v1/quality/pbis/{id}/quality:

    get:
      summary: Calcula o indicador de completude sobre o checklist vigente do PBI (PBI-01.3.6 / S1-15)
      operationId: getPbiCompleteness
      description: >-
        Calcula a proporção sem pesos das verificações habilitadas e aplicáveis. A verificação
        de protótipo só se aplica quando `requer_interface` é verdadeiro e consulta os protótipos
        vinculados ao PBI. Verificações
        não aplicáveis não são retornadas nem entram no denominador. O valor é calculado na
        consulta, não confiando no score persistido. A resposta informa a versão do conjunto
        de regras usado. A política organizacional é lida da configuração administrativa vigente.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Indicador e verificações consideradas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiCompletenessReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: PBI não encontrado

  /api/v1/quality/configuration/organization:
    get:
      summary: Consulta a política de qualidade de cada nível (S2-19)
      operationId: getOrganizationQualityConfiguration
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Política atual, padrões do guia e autoria/data da revisão
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OrganizationQualityConfiguration'}
        '401': {$ref: '#/components/responses/Unauthorized'}
    put:
      summary: Administrador configura verificações por nível e termos vagos
      operationId: updateOrganizationQualityConfiguration
      security: [{cookieAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [expected_version, levels, vague_terms, exigir_justificativa_item_concluido]
              properties:
                expected_version: {type: integer, minimum: 1, maximum: 2147483647}
                levels: {$ref: '#/components/schemas/OrganizationQualityLevels'}
                vague_terms: {$ref: '#/components/schemas/OrganizationVagueTerms'}
                exigir_justificativa_item_concluido: {type: boolean}
      responses:
        '200':
          description: Nova revisão aplicada imediatamente; conclusões anteriores não são alteradas
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OrganizationQualityConfiguration'}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Apenas administrador pode modificar a política}
        '409': {description: Revisão mudou desde a leitura; recarregue antes de salvar}

  /api/v1/quality/configuration/history:
    get:
      summary: Lista revisões da política com autor e data, exclusivo de administrador
      operationId: listOrganizationQualityHistory
      security: [{cookieAuth: []}]
      parameters:
        - {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 25}}
        - {name: before, in: query, schema: {type: integer, minimum: 1, maximum: 2147483647}}
      responses:
        '200':
          description: Revisões mais recentes primeiro
          content:
            application/json:
              schema:
                type: object
                required: [items, next_before]
                properties:
                  items: {type: array, items: {$ref: '#/components/schemas/OrganizationQualityConfiguration'}}
                  next_before: {type: integer, nullable: true}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Apenas administrador pode consultar este histórico}

  /api/v1/quality/items/{kind}/{id}:
    get:
      summary: Avalia qualidade conforme a organização e identifica critérios da conclusão
      operationId: evaluateOrganizationItemQuality
      security: [{cookieAuth: []}]
      parameters:
        - {name: kind, in: path, required: true, schema: {type: string, enum: [epico, feature, pbi]}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Indicador atual e política original da conclusão, quando documentada
          content:
            application/json:
              schema:
                type: object
                required: [entity_type, entity_id, status, configuration_version, rule_version, checks, score_completude, completion]
                properties:
                  entity_type: {type: string, enum: [epico, feature, pbi]}
                  entity_id: {type: string, format: uuid}
                  status: {type: string}
                  configuration_version: {type: integer}
                  rule_version: {type: string}
                  score_completude: {type: integer, minimum: 0, maximum: 100, nullable: true}
                  checks:
                    type: array
                    description: Somente verificações ativas e aplicáveis entram no indicador
                    items:
                      type: object
                      required: [check_id, check_name, passed, is_blocking, message]
                      properties:
                        check_id: {type: string}
                        check_name: {type: string}
                        passed: {type: boolean}
                        is_blocking: {type: boolean}
                        message: {type: string}
                  completion:
                    type: object
                    nullable: true
                    description: Nulo para rascunho; versão/configuração nulas indicam avaliação legada sem documentação
                    properties:
                      configuration_version: {type: integer, nullable: true}
                      evaluated_at: {type: string, format: date-time, nullable: true}
                      evaluated_by: {type: string, format: uuid, nullable: true}
                      previous_criteria: {type: boolean}
                      configuration:
                        nullable: true
                        allOf: [{$ref: '#/components/schemas/OrganizationQualityConfiguration'}]
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Item inexistente ou sem acesso ao projeto}

  /api/v1/quality/configuration/pbi:
    get:
      summary: Consulta a política organizacional das verificações de qualidade de PBI (S2-19 parcial)
      operationId: getPbiQualityConfiguration
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Política vigente, versão e dados de auditoria da última alteração
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiQualityConfiguration'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      summary: Atualiza verificações habilitadas e termos vagos organizacionais (somente admin)
      operationId: updatePbiQualityConfiguration
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PbiQualityConfigurationInput'
      responses:
        '200':
          description: Nova configuração versionada, registrada com autor, data e trilha de auditoria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PbiQualityConfiguration'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Apenas administradores podem alterar a configuração
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/audit/{entidade_tipo}/{entidade_id}/versions:
    get:
      summary: Lista snapshots da especificação por autor e data (S2-16)
      operationId: listItemVersions
      description: >-
        Exige acesso ao projeto. Ordena por versão decrescente. A referência inicial
        de itens legados é identificada por REFERENCIA_INICIAL, sem autoria histórica presumida.
      security:
        - cookieAuth: []
      parameters:
        - &versionEntityType
          name: entidade_tipo
          in: path
          required: true
          schema: {type: string, enum: [epico, feature, pbi]}
        - &versionEntityId
          name: entidade_id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 100, default: 25}
        - name: before
          in: query
          description: Continua a página abaixo deste número de versão
          schema: {type: integer, minimum: 1, maximum: 2147483647}
        - name: autor_id
          in: query
          schema: {type: string, format: uuid}
        - name: desde
          in: query
          description: Início inclusivo, data ISO com fuso horário
          schema: {type: string, format: date-time}
        - name: ate
          in: query
          description: Fim inclusivo, não anterior a desde
          schema: {type: string, format: date-time}
      responses:
        '200':
          description: Página de versões, mais recente primeiro
          content:
            application/json:
              schema:
                type: object
                required: [items, next_before]
                properties:
                  items:
                    type: array
                    items: {$ref: '#/components/schemas/ItemVersion'}
                  next_before: {type: integer, nullable: true}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Item inexistente ou sem acesso ao projeto}

  /api/v1/audit/{entidade_tipo}/{entidade_id}/versions/compare:
    get:
      summary: Compara os campos de dois snapshots do mesmo item (S2-16)
      operationId: compareItemVersions
      security:
        - cookieAuth: []
      parameters:
        - *versionEntityType
        - *versionEntityId
        - name: de
          in: query
          required: true
          schema: {type: integer, minimum: 1, maximum: 2147483647}
        - name: para
          in: query
          required: true
          schema: {type: integer, minimum: 1, maximum: 2147483647}
      responses:
        '200':
          description: Snapshots selecionados e somente os campos diferentes, sem alterar o item
          content:
            application/json:
              schema:
                type: object
                required: [anterior, nova, campos]
                properties:
                  anterior: {$ref: '#/components/schemas/ItemVersionSnapshot'}
                  nova: {$ref: '#/components/schemas/ItemVersionSnapshot'}
                  campos:
                    type: array
                    items:
                      type: object
                      required: [campo, anterior, novo]
                      properties:
                        campo: {type: string}
                        anterior: {nullable: true, description: Valor JSON na origem}
                        novo: {nullable: true, description: Valor JSON no destino}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Item inacessível ou versão inexistente no item informado}

  /api/v1/audit/{entidade_tipo}/{entidade_id}/history:
    get:
      summary: Consulta o histórico de auditoria paginado de uma entidade
      operationId: getEntityAuditHistory
      security:
        - cookieAuth: []
      parameters:
        - name: entidade_tipo
          in: path
          required: true
          schema:
            type: string
            enum: [epico, feature, pbi]
        - name: entidade_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          description: Cursor opaco retornado pela página anterior
          schema:
            type: string
      responses:
        '200':
          description: Eventos ordenados do mais recente para o mais antigo
          content:
            application/json:
              schema:
                type: object
                required: [items, next_cursor]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditHistoryItem'
                  next_cursor:
                    type: string
                    nullable: true
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Entidade não encontrada

  /api/v1/criteria:
    post:
      summary: Registra um critério de aceitação polimórfico (PBI-01.2.1, PBI-01.2.2, PBI-01.2.3 / S1-10)
      operationId: createCriterion
      description: >-
        Épico e feature exigem texto livre; PBI exige nome, DADO, QUANDO e ENTÃO em conjunto.
        Novo critério é sempre adicionado ao final da ordem existente na entidade. Para item concluído,
        a política organizacional pode exigir justificativa, armazenada na auditoria da mutação.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCriterionRequest'
      responses:
        '201':
          description: Critério adicionado ao final da lista da entidade
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CriterionResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Entidade referenciada não encontrada

    get:
      summary: Lista critérios de aceitação ordenados de uma entidade (S1-10)
      operationId: listCriteria
      security:
        - cookieAuth: []
      parameters:
        - name: entidade_tipo
          in: query
          required: true
          schema:
            type: string
            enum: [epico, feature, pbi]
        - name: entidade_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Critérios ordenados da entidade
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CriterionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/criteria/{id}:
    delete:
      summary: Remove um critério de aceitação e reordena os demais da mesma entidade (PBI-01.2.1 / S1-10)
      operationId: deleteCriterion
      description: A política organizacional pode exigir justificativa ao alterar critérios de item concluído.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                justificativa:
                  type: string
                  maxLength: 2000
      responses:
        '200':
          description: Critério removido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CriterionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Critério não encontrado

  /api/v1/criteria/{id}/move:
    patch:
      summary: Reordena um critério em relação aos demais da mesma entidade (PBI-01.2.4 / S1-12)
      operationId: moveCriterion
      description: >-
        Operação idempotente: mover o primeiro item para cima (ou o último para baixo) não
        retorna erro, apenas devolve a lista sem alteração. Para item concluído, a política
        organizacional pode exigir justificativa para uma movimentação efetiva.
      security:
        - cookieAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [direction]
              properties:
                direction:
                  type: string
                  enum: [up, down]
                justificativa:
                  type: string
                  maxLength: 2000
      responses:
        '200':
          description: Lista ordenada da entidade após a movimentação
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CriterionResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Critério não encontrado

  /api/v1/projects/{id}/decisions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as decisões do projeto e as herdadas dos ascendentes (S1-18)
      description: >
        Ordem cronológica (mais antiga primeiro), com autor e data. Decisões de
        níveis acima vêm com `origem.herdada = true`; decisões de descendentes
        nunca aparecem.
      operationId: listProjectsDecisions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Decisões do item e dos ascendentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Registra uma decisão no projeto (S1-18)
      description: >
        Contexto, decisão e justificativa são obrigatórios; alternativas
        descartadas são opcionais. Registrar decisão nunca é exigido para
        concluir um item. Apenas admin e po.
      operationId: createProjectsDecision
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionInput'
      responses:
        '201':
          description: Decisão registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado
        '409':
          description: Item ou ancestral arquivado (somente leitura)

  /api/v1/epics/{id}/decisions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as decisões do épico e as herdadas dos ascendentes (S1-18)
      description: >
        Ordem cronológica (mais antiga primeiro), com autor e data. Decisões de
        níveis acima vêm com `origem.herdada = true`; decisões de descendentes
        nunca aparecem.
      operationId: listEpicsDecisions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Decisões do item e dos ascendentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Registra uma decisão no épico (S1-18)
      description: >
        Contexto, decisão e justificativa são obrigatórios; alternativas
        descartadas são opcionais. Registrar decisão nunca é exigido para
        concluir um item. Apenas admin e po.
      operationId: createEpicsDecision
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionInput'
      responses:
        '201':
          description: Decisão registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado
        '409':
          description: Item ou ancestral arquivado (somente leitura)

  /api/v1/features/{id}/decisions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as decisões do feature e as herdadas dos ascendentes (S1-18)
      description: >
        Ordem cronológica (mais antiga primeiro), com autor e data. Decisões de
        níveis acima vêm com `origem.herdada = true`; decisões de descendentes
        nunca aparecem.
      operationId: listFeaturesDecisions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Decisões do item e dos ascendentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Registra uma decisão no feature (S1-18)
      description: >
        Contexto, decisão e justificativa são obrigatórios; alternativas
        descartadas são opcionais. Registrar decisão nunca é exigido para
        concluir um item. Apenas admin e po.
      operationId: createFeaturesDecision
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionInput'
      responses:
        '201':
          description: Decisão registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado
        '409':
          description: Item ou ancestral arquivado (somente leitura)

  /api/v1/pbis/{id}/decisions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as decisões do PBI e as herdadas dos ascendentes (S1-18)
      description: >
        Ordem cronológica (mais antiga primeiro), com autor e data. Decisões de
        níveis acima vêm com `origem.herdada = true`; decisões de descendentes
        nunca aparecem.
      operationId: listPbisDecisions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Decisões do item e dos ascendentes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Registra uma decisão no PBI (S1-18)
      description: >
        Contexto, decisão e justificativa são obrigatórios; alternativas
        descartadas são opcionais. Registrar decisão nunca é exigido para
        concluir um item. Apenas admin e po.
      operationId: createPbisDecision
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionInput'
      responses:
        '201':
          description: Decisão registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Decision'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado
        '409':
          description: Item ou ancestral arquivado (somente leitura)

  /api/v1/epics/{id}/suggestions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as sugestões da IA para o épico (S2-13)
      description: Pendentes primeiro; nenhuma sugestão altera o item sem aceite explícito.
      operationId: listEpicsSuggestions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Sugestões do item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Propõe uma sugestão para um campo do épico (S2-13)
      description: >
        Staging da IA: nunca grava diretamente no item. Uma nova proposta para
        o mesmo campo substitui a sugestão pendente existente (idempotente).
        Apenas admin e po.
      operationId: createEpicsSuggestion
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestionInput'
      responses:
        '201':
          description: Sugestão pendente criada ou atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado

  /api/v1/epics/{id}/suggestions/{suggestionId}/accept:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Aceita a sugestão e aplica o valor ao épico (S2-13)
      description: >
        Idempotente: repetir a mesma aceitação retorna 200 sem duplicar.
        Marca o campo como ai-accepted na proveniência. Apenas admin e po.
      operationId: acceptEpicsSuggestion
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveAcceptInput'
      responses:
        '200':
          description: Sugestão aceita e campo atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Item ou ancestral arquivado, ou sugestão já resolvida de outra forma

  /api/v1/epics/{id}/suggestions/{suggestionId}/edit:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Edita a sugestão e aplica o novo valor ao épico (S2-13)
      description: >
        Idempotente: repetir a mesma edição retorna 200. Preserva o texto
        originalmente sugerido e marca o campo como ai-edited. Apenas admin e po.
      operationId: editEpicsSuggestion
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveEditInput'
      responses:
        '200':
          description: Sugestão editada e campo atualizado com o novo valor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Item ou ancestral arquivado, ou sugestão já resolvida de outra forma

  /api/v1/epics/{id}/suggestions/{suggestionId}/discard:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Descarta a sugestão sem alterar o épico (S2-13)
      description: Nunca escreve no item. Idempotente. Apenas admin e po.
      operationId: discardEpicsSuggestion
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Sugestão descartada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Sugestão já resolvida de outra forma

  /api/v1/features/{id}/suggestions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as sugestões da IA para o feature (S2-13)
      description: Pendentes primeiro; nenhuma sugestão altera o item sem aceite explícito.
      operationId: listFeaturesSuggestions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Sugestões do item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Propõe uma sugestão para um campo do feature (S2-13)
      description: >
        Staging da IA: nunca grava diretamente no item. Uma nova proposta para
        o mesmo campo substitui a sugestão pendente existente (idempotente).
        Apenas admin e po.
      operationId: createFeaturesSuggestion
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestionInput'
      responses:
        '201':
          description: Sugestão pendente criada ou atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado

  /api/v1/features/{id}/suggestions/{suggestionId}/accept:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Aceita a sugestão e aplica o valor ao feature (S2-13)
      description: >
        Idempotente: repetir a mesma aceitação retorna 200 sem duplicar.
        Marca o campo como ai-accepted na proveniência. Apenas admin e po.
      operationId: acceptFeaturesSuggestion
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveAcceptInput'
      responses:
        '200':
          description: Sugestão aceita e campo atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Item ou ancestral arquivado, ou sugestão já resolvida de outra forma

  /api/v1/features/{id}/suggestions/{suggestionId}/edit:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Edita a sugestão e aplica o novo valor ao feature (S2-13)
      description: >
        Idempotente: repetir a mesma edição retorna 200. Preserva o texto
        originalmente sugerido e marca o campo como ai-edited. Apenas admin e po.
      operationId: editFeaturesSuggestion
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveEditInput'
      responses:
        '200':
          description: Sugestão editada e campo atualizado com o novo valor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Item ou ancestral arquivado, ou sugestão já resolvida de outra forma

  /api/v1/features/{id}/suggestions/{suggestionId}/discard:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Descarta a sugestão sem alterar o feature (S2-13)
      description: Nunca escreve no item. Idempotente. Apenas admin e po.
      operationId: discardFeaturesSuggestion
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Sugestão descartada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Sugestão já resolvida de outra forma

  /api/v1/pbis/{id}/suggestions:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
    get:
      summary: Lista as sugestões da IA para o PBI (S2-13)
      description: Pendentes primeiro; nenhuma sugestão altera o item sem aceite explícito.
      operationId: listPbisSuggestions
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Sugestões do item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestionList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Item não encontrado
    post:
      summary: Propõe uma sugestão para um campo do PBI (S2-13)
      description: >
        Staging da IA: nunca grava diretamente no item. Uma nova proposta para
        o mesmo campo substitui a sugestão pendente existente (idempotente).
        Apenas admin e po.
      operationId: createPbisSuggestion
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuggestionInput'
      responses:
        '201':
          description: Sugestão pendente criada ou atualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item não encontrado

  /api/v1/pbis/{id}/suggestions/{suggestionId}/accept:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Aceita a sugestão e aplica o valor ao PBI (S2-13)
      description: >
        Idempotente: repetir a mesma aceitação retorna 200 sem duplicar.
        Marca o campo como ai-accepted na proveniência. Apenas admin e po.
      operationId: acceptPbisSuggestion
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveAcceptInput'
      responses:
        '200':
          description: Sugestão aceita e campo atualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Item ou ancestral arquivado, ou sugestão já resolvida de outra forma

  /api/v1/pbis/{id}/suggestions/{suggestionId}/edit:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Edita a sugestão e aplica o novo valor ao PBI (S2-13)
      description: >
        Idempotente: repetir a mesma edição retorna 200. Preserva o texto
        originalmente sugerido e marca o campo como ai-edited. Apenas admin e po.
      operationId: editPbisSuggestion
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveEditInput'
      responses:
        '200':
          description: Sugestão editada e campo atualizado com o novo valor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Item ou ancestral arquivado, ou sugestão já resolvida de outra forma

  /api/v1/pbis/{id}/suggestions/{suggestionId}/discard:
    parameters:
      - name: id
        in: path
        required: true
        schema: {type: string, format: uuid}
      - name: suggestionId
        in: path
        required: true
        schema: {type: string, format: uuid}
    post:
      summary: Descarta a sugestão sem alterar o PBI (S2-13)
      description: Nunca escreve no item. Idempotente. Apenas admin e po.
      operationId: discardPbisSuggestion
      security:
        - cookieAuth: []
      responses:
        '200':
          description: Sugestão descartada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suggestion'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item ou sugestão não encontrados
        '409':
          description: Sugestão já resolvida de outra forma

  /api/v1/projects/{projectId}/similar-items:
    parameters:
      - name: projectId
        in: path
        required: true
        description: Projeto em que o item está sendo escrito
        schema: {type: string, format: uuid}
    post:
      summary: Sugere itens semelhantes enquanto o item é escrito (S2-12)
      description: >
        Consulta somente leitura (POST apenas para transportar o texto em
        edição). Diferentemente da busca, o acervo é consultado em todos os
        projetos que o usuário pode acessar; cada item informa o projeto de
        origem e `outro_projeto`. Só entram itens já indexados, não arquivados
        e acima do limiar de similaridade, no máximo 5. Texto curto, nada
        semelhante ou serviço de embeddings indisponível (`degradado: true`)
        resultam em `items: []` com 200, sem interromper a escrita. Nada é
        gravado.
      operationId: searchSimilarItems
      security:
        - cookieAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarItemsSearchInput'
      responses:
        '200':
          description: Itens semelhantes, do mais para o menos similar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarItemsResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado ou sem acesso

  /api/v1/epics/{id}/similar-items/{origemId}/reuse:
    parameters:
      - name: id
        in: path
        required: true
        description: Item em edição que receberá a proposta
        schema: {type: string, format: uuid}
      - name: origemId
        in: path
        required: true
        description: Item semelhante a aproveitar (mesmo nível)
        schema: {type: string, format: uuid}
    post:
      summary: Aproveita um item semelhante como proposta editável no épico (S2-12)
      description: >
        Copia os campos de texto do item de origem para sugestões pendentes do
        item em edição (origem `similar:<tipo>:<id>`), que a pessoa aceita,
        edita ou descarta pelo fluxo de S2-13, e registra a relação de origem.
        Não altera o item. Repetir o aproveitamento atualiza as propostas
        pendentes e a relação. Apenas admin e po.
      operationId: reuseEpicsSimilarItem
      security:
        - cookieAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarItemsReuseInput'
      responses:
        '201':
          description: Propostas pendentes criadas e relação registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarItemsReuseResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item em edição ou item de origem não encontrado
        '409':
          description: Item em edição ou item de origem arquivado

  /api/v1/features/{id}/similar-items/{origemId}/reuse:
    parameters:
      - name: id
        in: path
        required: true
        description: Item em edição que receberá a proposta
        schema: {type: string, format: uuid}
      - name: origemId
        in: path
        required: true
        description: Item semelhante a aproveitar (mesmo nível)
        schema: {type: string, format: uuid}
    post:
      summary: Aproveita um item semelhante como proposta editável no feature (S2-12)
      description: >
        Copia os campos de texto do item de origem para sugestões pendentes do
        item em edição (origem `similar:<tipo>:<id>`), que a pessoa aceita,
        edita ou descarta pelo fluxo de S2-13, e registra a relação de origem.
        Não altera o item. Repetir o aproveitamento atualiza as propostas
        pendentes e a relação. Apenas admin e po.
      operationId: reuseFeaturesSimilarItem
      security:
        - cookieAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarItemsReuseInput'
      responses:
        '201':
          description: Propostas pendentes criadas e relação registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarItemsReuseResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item em edição ou item de origem não encontrado
        '409':
          description: Item em edição ou item de origem arquivado

  /api/v1/pbis/{id}/similar-items/{origemId}/reuse:
    parameters:
      - name: id
        in: path
        required: true
        description: Item em edição que receberá a proposta
        schema: {type: string, format: uuid}
      - name: origemId
        in: path
        required: true
        description: Item semelhante a aproveitar (mesmo nível)
        schema: {type: string, format: uuid}
    post:
      summary: Aproveita um item semelhante como proposta editável no PBI (S2-12)
      description: >
        Copia os campos de texto do item de origem para sugestões pendentes do
        item em edição (origem `similar:<tipo>:<id>`), que a pessoa aceita,
        edita ou descarta pelo fluxo de S2-13, e registra a relação de origem.
        Não altera o item. Repetir o aproveitamento atualiza as propostas
        pendentes e a relação. Apenas admin e po.
      operationId: reusePbisSimilarItem
      security:
        - cookieAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimilarItemsReuseInput'
      responses:
        '201':
          description: Propostas pendentes criadas e relação registrada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarItemsReuseResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Item em edição ou item de origem não encontrado
        '409':
          description: Item em edição ou item de origem arquivado

  /api/v1/auth/register:
    post:
      summary: Cria uma conta; PO e administrador exigem sessão de administrador
      description: Cadastro público cria dev e sua sessão na mesma transação; falha ao gravar a sessão desfaz a conta e permite nova tentativa. Com sessão válida existente, cria a conta sem emitir novo token ou substituir o cookie atual. Cadastros concorrentes do mesmo e-mail retornam EMAIL_EXISTS para a tentativa duplicada.
      operationId: registerUser
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [nome, email, password]
              properties:
                nome: {type: string, minLength: 2}
                email: {type: string, format: email}
                password: {type: string, minLength: 6}
                role: {type: string, enum: [po, dev, admin], default: dev, description: "po e admin só são aceitos com sessão de administrador"}
      responses:
        '201':
          description: Conta criada. Sessão iniciada apenas no cadastro sem sessão válida anterior.
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          description: Tentativa de criar PO ou administrador sem sessão de administrador
        '409':
          description: E-mail já cadastrado

  /api/v1/chat/projects:
    get:
      summary: Lista projetos permitidos no chat (admin/PO ou alocação ativa do desenvolvedor)
      operationId: listChatProjects
      security: [{cookieAuth: []}]
      responses:
        '200': {description: Lista items com id e nome dos projetos}
        '401': {$ref: '#/components/responses/Unauthorized'}
  /api/v1/projects/{projectId}/documents/{documentId}/reprocess:
    parameters:
      - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
      - {name: documentId, in: path, required: true, schema: {type: string, format: uuid}}
    post:
      summary: Reenfileira a ingestão de um documento (admin ou PO)
      description: Pedidos repetidos enquanto pendente preservam a fila e os contadores. Tentativas ativas retornam 409. A indexação substitui atomicamente os trechos do documento.
      operationId: reprocessDocument
      security: [{cookieAuth: []}]
      responses:
        '202': {description: Documento pendente para reprocessamento}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Sem permissão de escrita}
        '404': {description: Projeto ou documento inexistente}
        '409': {description: Projeto arquivado ou documento ainda em processamento}

  /api/v1/chat/conversations:
    get:
      summary: Lista as conversas do usuário autenticado
      operationId: listChatConversations
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Conversas do usuário, da mais recente para a mais antiga
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Cria uma conversa (opcionalmente escopada a um projeto)
      operationId: createChatConversation
      security: [{cookieAuth: []}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                titulo: {type: string, maxLength: 120}
                projeto_id: {type: string, format: uuid}
      responses:
        '201':
          description: Conversa criada
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado

  /api/v1/chat/conversations/{id}/messages:
    get:
      summary: Mensagens de uma conversa do próprio usuário
      description: Conversa de outra pessoa retorna 404, sem revelar a existência.
      operationId: listChatMessages
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Mensagens em ordem cronológica
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Conversa não encontrada

  /api/v1/chat/query:
    post:
      summary: Envia uma pergunta ao assistente e registra a troca
      description: >
        Projeto obrigatório em novas conversas; em conversas existentes o projeto é imutável.
        Somente admin/PO ou desenvolvedor com alocação ativa pode consultar o projeto.
        Sem evidência no acervo, responde "Informação não encontrada no acervo
        do projeto." sem inventar fontes. `origem` informa se a resposta veio
        do assistente, de busca textual (assistente indisponível) ou sem resultado.
      operationId: askChatQuestion
      security: [{cookieAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pergunta]
              properties:
                pergunta: {type: string, minLength: 1, maxLength: 2000}
                conversa_id: {type: string, format: uuid}
                projeto_id: {type: string, format: uuid}
      responses:
        '200':
          description: Resposta com fontes
          content:
            application/json:
              schema:
                type: object
                required: [conversa_id, resposta, fontes, origem]
                properties:
                  conversa_id: {type: string, format: uuid}
                  resposta: {type: string}
                  fontes:
                    type: array
                    items:
                      type: object
                      properties:
                        id: {type: string}
                        titulo: {type: string}
                        tipo: {type: string}
                  origem: {type: string, enum: [assistente, busca_textual, sem_resultado]}
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Conversa (de outro usuário incluída) ou projeto não encontrado

  /api/v1/projects/{projectId}/repo-analyses:
    parameters:
      - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
    get:
      summary: Lista as análises de repositório do projeto
      operationId: listRepoAnalyses
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Análises do projeto, da mais recente para a mais antiga
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
    post:
      summary: Inicia uma análise de repositório público do GitHub
      description: Apenas PO e administrador podem iniciar análises. Desenvolvedores com acesso ao projeto podem consultar as análises e os relatórios.
      operationId: startRepoAnalysis
      security: [{cookieAuth: []}]
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema: {type: string, format: uuid}
          description: Reutilize a mesma chave ao repetir o envio da mesma solicitação.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [repositorio_url]
              properties:
                repositorio_url: {type: string, example: "https://github.com/usuario/repositorio"}
                perfil:
                  type: string
                  enum: [quick, balanced, complete]
                  default: quick
                  description: Limite priorizado de arquivos para análise; quick e balanced reduzem chamadas ao modelo local.
      responses:
        '201':
          description: Solicitação persistida na fila; despacho assíncrono e idempotente
        '403':
          description: Apenas PO e administrador podem iniciar análises
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
        '409':
          description: Projeto arquivado é somente leitura
        '503':
          description: Motor de análise indisponível

  /api/v1/projects/{projectId}/repo-analyses/{id}:
    get:
      summary: Detalhes de uma análise do projeto
      operationId: getRepoAnalysis
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Análise com etapa, progresso e relatório quando concluída
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto ou análise não encontrados

  /api/v1/projects/{projectId}/repo-analyses/{id}/pause:
    post:
      summary: Pausar após concluir o arquivo atual e salvar checkpoint
      description: Requer papel PO ou administrador e acesso ao projeto.
      operationId: pauseRepoAnalysis
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Análise pausada ou aguardando o ponto seguro de pausa}
        '403': {description: Apenas PO e administrador podem controlar análises}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Projeto ou análise não encontrados}
        '409': {description: Estado da análise não permite pausa}

  /api/v1/projects/{projectId}/repo-analyses/{id}/resume:
    post:
      summary: Retomar análise a partir do checkpoint salvo
      description: Requer papel PO ou administrador e acesso ao projeto.
      operationId: resumeRepoAnalysis
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Retomada registrada na fila}
        '403': {description: Apenas PO e administrador podem controlar análises}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Projeto ou análise não encontrados}
        '409': {description: Estado da análise não permite retomada}

  /api/v1/projects/{projectId}/repo-analyses/{id}/cancel:
    post:
      summary: Cancelar definitivamente a análise
      description: Requer papel PO ou administrador e acesso ao projeto.
      operationId: cancelRepoAnalysis
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Análise cancelada ou aguardando o ponto seguro de cancelamento}
        '403': {description: Apenas PO e administrador podem controlar análises}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '404': {description: Projeto ou análise não encontrados}
        '409': {description: Estado da análise não permite cancelamento}

  /api/v1/projects/{projectId}/repo-analyses/{id}/report/approve:
    post:
      summary: Aprovar a versão revisada do relatório de IA e publicar no acervo (PO/admin)
      operationId: approveRepoReport
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [relatorio_revisao]
              properties:
                relatorio_revisao: {type: integer, minimum: 0}
      responses:
        '200': {description: Versão aprovada com autor/data e indexação enfileirada}
        '400': {description: Versão ausente ou inválida}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Somente PO e administrador podem aprovar}
        '404': {description: Projeto ou análise não encontrados}
        '409': {description: Projeto arquivado, relatório indisponível ou versão alterada}

  /api/v1/projects/{projectId}/repo-analyses/{id}/indexing/retry:
    post:
      summary: Reprocessar o relatório concluído no acervo (PO ou administrador)
      operationId: retryRepoReportIndexing
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Reprocessamento registrado ou já em andamento}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Sem permissão de escrita}
        '404': {description: Projeto ou análise não encontrados}
        '409': {description: Projeto arquivado, relatório ainda não concluído ou sem aprovação humana}

  /api/v1/search:
    get:
      summary: Busca híbrida por texto e significado no acervo, sempre isolada por projeto
      description: Valida o acesso do usuário autenticado ao projeto antes de gerar embeddings ou consultar o acervo. PO e administrador seguem a política global; desenvolvedores precisam de alocação vigente. Projeto inexistente ou sem acesso retorna 404.
      operationId: searchKnowledge
      security: [{cookieAuth: []}]
      parameters:
        - {name: q, in: query, required: true, schema: {type: string, minLength: 3, maxLength: 200}}
        - {name: projeto_id, in: query, required: true, schema: {type: string, format: uuid}}
        - {name: tecnologia_id, in: query, required: false, schema: {type: string, format: uuid}}
        - name: nivel
          in: query
          required: false
          schema:
            type: string
            enum: [documento, decisao, epico, feature, pbi, analise_repositorio]
        - {name: limit, in: query, required: false, schema: {type: integer, minimum: 1, maximum: 50, default: 10}}
      responses:
        '200':
          description: Resultados ordenados por fusão da classificação vetorial e textual
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HybridSearchResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404': {description: Projeto não encontrado}
        '502': {description: Serviço de embeddings indisponível ou resposta incompatível}
        '503': {description: Serviço local de embeddings indisponível}

  /api/v1/developers:
    get:
      summary: Desenvolvedores, tecnologias e competências
      operationId: listDevelopers
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Mapeamento de competências
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/admin/stats:
    get:
      summary: Indicadores administrativos
      operationId: adminStats
      security: [{cookieAuth: []}]
      responses:
        '200':
          description: Contagens da base
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Somente administrador

  /api/v1/admin/ingestion:
    get:
      summary: Observabilidade do pipeline de ingestão de documentos (S2-01/S2-02)
      description: >
        Snapshot em tempo real do estado do worker: contagens por status
        (pendente/processando/processado/falha), documentos ativos, falhas
        recentes e últimas atualizações. Substitui o editor do n8n como
        ferramenta visual para admin acompanhar a fila. Somente administrador.
      operationId: adminIngestionSnapshot
      security: [{cookieAuth: []}]
      parameters:
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 100, default: 25}
      responses:
        '200':
          description: Snapshot do pipeline
          content:
            application/json:
              schema:
                type: object
                required: [counts, recent, active, failed, generated_at]
                properties:
                  counts:
                    type: object
                    required: [pendente, processando, processado, falha]
                    properties:
                      pendente: {type: integer, minimum: 0}
                      processando: {type: integer, minimum: 0}
                      processado: {type: integer, minimum: 0}
                      falha: {type: integer, minimum: 0}
                  recent: {type: array, items: {type: object}}
                  active: {type: array, items: {type: object}}
                  failed: {type: array, items: {type: object}}
                  generated_at: {type: string, format: date-time}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Somente administrador

  /api/v1/admin/demo-seed:
    post:
      summary: Carrega exemplos demonstrativos em um projeto explícito (somente administrador)
      description: Carga idempotente e auditada. Não gera vetores nem reindexa documentos. Projetos arquivados são rejeitados.
      operationId: adminLoadDemo
      security: [{cookieAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [projeto_id]
              additionalProperties: false
              properties:
                projeto_id: {type: string, format: uuid}
      responses:
        '200':
          description: Carga concluída; inseridos é zero quando já aplicada
          content:
            application/json:
              schema:
                type: object
                properties:
                  projeto_id: {type: string, format: uuid}
                  inseridos: {type: integer, minimum: 0, maximum: 2}
                  status: {type: string, enum: [sucesso]}
                  message: {type: string}
        '400':
          description: Projeto de destino ausente ou inválido
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Somente administrador
        '404':
          description: Projeto não encontrado
        '409':
          description: Projeto arquivado

  /api/v1/admin/ingest-seed:
    post:
      deprecated: true
      summary: Carrega exemplos demonstrativos em um projeto explícito (somente administrador)
      description: Carga idempotente e auditada. Não gera vetores nem reindexa documentos. Projetos arquivados são rejeitados.
      operationId: adminIngestSeed
      security: [{cookieAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [projeto_id]
              additionalProperties: false
              properties:
                projeto_id: {type: string, format: uuid}
      responses:
        '200':
          description: Carga concluída; inseridos é zero quando já aplicada
          content:
            application/json:
              schema:
                type: object
                properties:
                  projeto_id: {type: string, format: uuid}
                  inseridos: {type: integer, minimum: 0, maximum: 2}
                  status: {type: string, enum: [sucesso]}
                  message: {type: string}
        '400':
          description: Projeto de destino ausente ou inválido
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Somente administrador
        '404':
          description: Projeto não encontrado
        '409':
          description: Projeto arquivado

  /api/v1:
    get:
      summary: Informações e módulos da API
      operationId: apiRoot
      security: []
      responses:
        '200':
          description: Nome, versão e módulos

  /api/v1/projects/{projectId}/backlog-search:
    get:
      summary: Busca textual relacional no backlog do projeto (S1-17)
      description: >
        Pesquisa título, descrição (épico/feature), história e regras (PBI) e o
        código do PBI, sem diferenciar acentos ou maiúsculas. Todos os termos
        precisam aparecer (interseção) e a busca combina por interseção com
        `status` e `tecnologia`. Nunca retorna itens de outro projeto. Não é
        busca semântica/RAG.
      operationId: searchProjectBacklog
      security:
        - cookieAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: q
          in: query
          required: true
          description: Termo(s) com 2 a 100 caracteres
          schema: {type: string, minLength: 2, maxLength: 100}
        - name: status
          in: query
          required: false
          schema: {type: string, enum: [rascunho, ativo, pronto, concluido, arquivado]}
        - name: tecnologia
          in: query
          required: false
          description: ID da tecnologia associada ao próprio item
          schema: {type: string, format: uuid}
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 100, default: 50}
      responses:
        '200':
          description: Resultados ordenados (título antes de descrição, depois hierarquia)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BacklogSearchResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado

  /api/v1/projects/{projectId}/documents:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Lista os documentos do projeto e os limites de envio (S1-20)
      description: >
        Paginação por cursor estável (created_at desc, id desc), sempre isolada
        pelo projeto da rota. Use `next_cursor` da resposta em `cursor` para a
        próxima página; `null` indica a última. `status_processamento` =
        `pendente` significa **aguardando ingestão**: o arquivo está armazenado,
        mas ainda não foi indexado (a ingestão pertence à S2-01).
      operationId: listProjectDocuments
      security:
        - cookieAuth: []
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor opaco devolvido em `next_cursor`
          schema: {type: string, maxLength: 512}
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 50, default: 20}
      responses:
        '200':
          description: Documentos exclusivos do projeto, do mais recente ao mais antigo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Projeto não encontrado
    post:
      summary: Envia um documento PDF, DOCX, MD ou TXT como corpo binário (S1-19)
      description: >
        O tipo real é verificado pelo conteúdo e pela extensão; o Content-Type
        informado pelo cliente não é considerado. O limite de tamanho é
        configurável até 20 MiB (DOCUMENT_MAX_SIZE_MB) e é informado em `limites.max_bytes`
        na listagem. Arquivos recusados não deixam arquivo nem registro.
      operationId: uploadProjectDocument
      security:
        - cookieAuth: []
      parameters:
        - name: X-File-Name
          in: header
          required: true
          description: Nome original do arquivo, codificado com encodeURIComponent
          schema:
            type: string
            maxLength: 765
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Documento armazenado com estado de processamento `pendente`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDocument'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Projeto não encontrado
        '409':
          description: Projeto arquivado é somente leitura (ARCHIVE_CONFLICT)
        '413':
          description: Arquivo acima do limite configurado
        '503':
          description: Armazenamento indisponível ou em recuperação; o envio pode ser repetido

  /api/v1/projects/{projectId}/documents/{documentId}:
    delete:
      summary: Remove o documento, o arquivo e o conteúdo indexado de forma idempotente (S1-22)
      description: >
        Repetir a chamada retorna 204 sem afetar outro conteúdo. Documento que
        não pertence ao projeto informado nunca é alterado. Quando há conteúdo
        indexado, um evento `document.removed` é gravado na mesma transação e
        publicado no webhook do n8n com o cabeçalho Idempotency-Key.
      operationId: deleteProjectDocument
      security:
        - cookieAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Documento removido ou já inexistente
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Perfil sem permissão de escrita
        '404':
          description: Projeto não encontrado
        '409':
          description: Projeto arquivado é somente leitura (ARCHIVE_CONFLICT); nada é removido
        '500':
          description: Falha na remoção; o documento permanece disponível
        '503':
          description: Armazenamento indisponível; o documento permanece disponível

  /api/v1/projects/{projectId}/documents/{documentId}/retry:
    post:
      summary: Agenda novamente a ingestão de um documento que falhou (S2-01/S2-02)
      operationId: retryProjectDocumentIngestion
      security: [{cookieAuth: []}]
      parameters:
        - {name: projectId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: documentId, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '202':
          description: Reprocessamento agendado
          content:
            application/json:
              schema:
                type: object
                required: [status_processamento]
                properties:
                  status_processamento: {type: string, enum: [pendente]}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '403': {description: Perfil sem permissão de escrita}
        '404': {description: Projeto ou documento não encontrado neste projeto}
        '409': {description: Projeto arquivado é somente leitura}

  /api/v1/projects/{projectId}/documents/{documentId}/chunks:
    post:
      summary: Persiste chunks indexados do documento (pipeline de ingestão, S2-02)
      description: >
        Endpoint server-to-server opcional usado pelo pipeline de ingestão.
        O fluxo canônico (worker) chama o ai-service direto e persiste pelos
        métodos internos do repository. Esta rota aceita `Authorization: Bearer <DOCUMENT_INGESTION_TOKEN>`
        separado da sessão de usuário. Cada embedding deve ter 1024 dimensões
        (bge-m3). Exige processamento_lease_id da reserva emitida pelo backend
        ao reivindicar o documento. Só grava com reserva vigente e estado processando.
        Reservas expiradas, canceladas pelo expurgo ou substituídas retornam 409.
        Repetir uma entrega concluída da mesma reserva retorna o resultado já salvo,
        sem substituir os chunks. Chamadores antigos precisam enviar a reserva;
        não há fallback para envio apenas com token de serviço.
      operationId: persistDocumentChunks
      security:
        - bearerAuth: []
      parameters:
        - name: projectId
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: documentId
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chunks, processamento_lease_id]
              properties:
                processamento_lease_id:
                  type: string
                  format: uuid
                  description: Reserva recebida do backend ao reivindicar o processamento do documento.
                chunks:
                  type: array
                  items:
                    type: object
                    required: [chunk_index, content, embedding]
                    properties:
                      chunk_index: {type: integer, minimum: 0}
                      content: {type: string}
                      metadata: {type: object, additionalProperties: true}
                      embedding:
                        type: array
                        minItems: 1024
                        maxItems: 1024
                        items: {type: number}
      responses:
        '200': {description: Chunks persistidos}
        '400': {$ref: '#/components/responses/ValidationError'}
        '401': {description: Token de ingestão ausente ou inválido}
        '404': {description: Projeto ou documento não encontrados}
        '409': {description: Projeto arquivado (ARCHIVE_CONFLICT) ou reserva expirada, cancelada ou substituída (CONFLICT)}

  /webhook/sinapse-document-removed:
    servers:
      - url: http://localhost:5678
        description: n8n (DOCUMENT_EVENTS_WEBHOOK_URL)
    post:
      summary: Evento publicado pelo backend quando um documento indexado é removido (S1-22 / PRE-03)
      description: >
        Entrega ao menos uma vez. O consumidor deve tratar `event_id` (também
        enviado em Idempotency-Key) como chave de deduplicação e excluir de
        forma idempotente todo o conteúdo indexado de `document_id` no escopo de
        `project_id`. Eventos não confirmados ficam pendentes no backend e são
        reenviados nas remoções seguintes.
      operationId: documentRemovedEvent
      security: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRemovedEvent'
      responses:
        '200':
          description: Evento aceito; qualquer 2xx confirma a entrega

  /ingest/document:
    post:
      summary: Solicita ingestão assíncrona de documento
      operationId: ingestDocument
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestDocumentRequest'
      responses:
        '200':
          description: Documento fragmentado e embeddings calculados
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestDocumentResponse'
        '400':
          $ref: '#/components/responses/ValidationError'

  /ingest/entity:
    post:
      summary: Indexa uma entidade estruturada
      operationId: ingestEntity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestEntityRequest'
      responses:
        '200':
          description: Entidade processada
        '400':
          $ref: '#/components/responses/ValidationError'

  /embeddings:
    post:
      summary: Gera embedding para um texto
      operationId: generateEmbedding
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: Vetor gerado
        '502':
          description: Ollama indisponível

  /rag/query:
    post:
      summary: Responde usando somente os trechos fornecidos
      operationId: queryRag
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RagQueryRequest'
      responses:
        '200':
          description: Resposta fundamentada
        '502':
          description: Ollama indisponível

  /api/v1/epics/{id}/archive-impact:
    get:
      summary: Prévia do arquivamento de epics (S1-09)
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Quantidades ainda não arquivadas, incluindo o próprio item
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HierarchyArchiveImpact'}
        '404': {description: Item não encontrado}
  /api/v1/epics/{id}/archive:
    patch:
      summary: Arquiva epics e descendentes com auditoria (S1-09)
      description: Exclusivo de PO/admin. Não apaga conteúdo. Repetições preservam data e auditoria. Conflito exige nova prévia.
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirmado, impacto]
              properties:
                confirmado: {type: boolean, enum: [true]}
                impacto: {$ref: '#/components/schemas/HierarchyArchiveImpact'}
                justificativa: {type: string, maxLength: 2000}
      responses:
        '200': {description: Item arquivado com archived_at}
        '400': {description: Confirmação ou prévia inválida}
        '403': {description: Perfil sem permissão de escrita}
        '404': {description: Item não encontrado}
        '409': {description: Impacto alterado ou ancestral somente leitura}

  /api/v1/features/{id}/archive-impact:
    get:
      summary: Prévia do arquivamento de features (S1-09)
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Quantidades ainda não arquivadas, incluindo o próprio item
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HierarchyArchiveImpact'}
        '404': {description: Item não encontrado}
  /api/v1/features/{id}/archive:
    patch:
      summary: Arquiva features e descendentes com auditoria (S1-09)
      description: Exclusivo de PO/admin. Não apaga conteúdo. Repetições preservam data e auditoria. Conflito exige nova prévia.
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirmado, impacto]
              properties:
                confirmado: {type: boolean, enum: [true]}
                impacto: {$ref: '#/components/schemas/HierarchyArchiveImpact'}
                justificativa: {type: string, maxLength: 2000}
      responses:
        '200': {description: Item arquivado com archived_at}
        '400': {description: Confirmação ou prévia inválida}
        '403': {description: Perfil sem permissão de escrita}
        '404': {description: Item não encontrado}
        '409': {description: Impacto alterado ou ancestral somente leitura}

  /api/v1/pbis/{id}/archive-impact:
    get:
      summary: Prévia do arquivamento de pbis (S1-09)
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Quantidades ainda não arquivadas, incluindo o próprio item
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HierarchyArchiveImpact'}
        '404': {description: Item não encontrado}
  /api/v1/pbis/{id}/archive:
    patch:
      summary: Arquiva pbis e descendentes com auditoria (S1-09)
      description: Exclusivo de PO/admin. Não apaga conteúdo. Repetições preservam data e auditoria. Conflito exige nova prévia.
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirmado, impacto]
              properties:
                confirmado: {type: boolean, enum: [true]}
                impacto: {$ref: '#/components/schemas/HierarchyArchiveImpact'}
                justificativa: {type: string, maxLength: 2000}
      responses:
        '200': {description: Item arquivado com archived_at}
        '400': {description: Confirmação ou prévia inválida}
        '403': {description: Perfil sem permissão de escrita}
        '404': {description: Item não encontrado}
        '409': {description: Impacto alterado ou ancestral somente leitura}

components:
  parameters:
    HarnessMode:
      in: path
      name: mode
      required: true
      schema: {type: string, enum: [levantamento, consulta, recomendacao]}
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: sinapse_session

  schemas:
    IndexEvent:
      type: object
      properties:
        evento_id: {type: string, format: uuid}
        projeto_id: {type: string, format: uuid}
        entidade_tipo: {type: string, enum: [epico, feature, pbi, decisao]}
        entidade_id: {type: string, format: uuid}
        versao: {type: integer, minimum: 1}
        operacao: {type: string, enum: [indexar, remover]}
        status: {type: string, enum: [pendente, processando, processado, falha]}
        tentativas: {type: integer, minimum: 0}
        proxima_tentativa: {type: string, format: date-time}
        erro_codigo:
          type: string
          nullable: true
          enum: [ATTEMPTS_EXHAUSTED, INVALID_RESPONSE, INVALID_SCOPE, TIMEOUT, SERVICE_HTTP_ERROR, SERVICE_UNAVAILABLE, PROCESSING_ERROR, null]
        updated_at: {type: string, format: date-time}
    HarnessConfig:
      type: object
      additionalProperties: false
      required: [instructions, operation_instructions, timeout_ms, rules]
      properties:
        instructions: {type: string, minLength: 1, maxLength: 12000}
        operation_instructions:
          type: object
          description: Chaves exatas das operações do modo
          additionalProperties: {type: string, minLength: 1, maxLength: 12000}
        timeout_ms: {type: integer, minimum: 1000, maximum: 60000}
        rules:
          type: object
          additionalProperties: false
          required: [vague_terms, macro_detail_terms, implementation_terms]
          properties:
            vague_terms: {type: array, maxItems: 40, items: {type: string, minLength: 1, maxLength: 60}}
            macro_detail_terms: {type: array, minItems: 1, maxItems: 40, items: {type: string, minLength: 1, maxLength: 60}}
            implementation_terms: {type: array, minItems: 1, maxItems: 40, items: {type: string, minLength: 1, maxLength: 60}}
            permission_terms:
              type: array
              minItems: 1
              maxItems: 40
              items: {type: string, minLength: 1, maxLength: 60}
              description: >
                Expressões que indicam ação sujeita a permissão na história ou nas regras do PBI. Quando
                algum aparece, as sugestões de cenários precisam incluir um acesso_nao_autorizado.
                Opcional ao salvar; revisões sem a lista usam o padrão do código.
    HarnessRevision:
      type: object
      required: [mode, version, schema_version, config, created_at, created_by]
      properties:
        mode: {type: string, enum: [levantamento, consulta, recomendacao]}
        version: {type: integer, minimum: 0}
        schema_version: {type: integer, enum: [1]}
        config: {$ref: "#/components/schemas/HarnessConfig"}
        created_at: {type: string, format: date-time, nullable: true}
        created_by: {type: string, format: uuid, nullable: true}
        output_schemas: {type: object, description: Schemas JSON por operação e nível; schema_version 1, additionalProperties false}


    PbiRelationView:
      type: object
      required:
        - id
        - pbi_id
        - relacionado_id
        - codigo
        - titulo
        - status
        - tipo
        - prioridade
        - tipo_relacao
        - direcao
        - rotulo
        - created_at
      properties:
        id:
          type: string
          format: uuid
        pbi_id:
          type: string
          format: uuid
        relacionado_id:
          type: string
          format: uuid
        codigo:
          type: string
        titulo:
          type: string
        status:
          type: string
        tipo:
          type: string
        prioridade:
          type: string
        tipo_relacao:
          type: string
          enum: [depende_de, similar_a, substitui]
        direcao:
          type: string
          enum: [saida, entrada]
        rotulo:
          type: string
        created_at:
          type: string
          format: date-time


    TechnologyOption:
      type: object
      required: [id, nome]
      properties:
        id:
          type: string
          format: uuid
        nome:
          type: string

    ProjectBacklogTreeResponse:
      type: object
      required: [project, epics, technologies]
      properties:
        project:
          type: object
          required: [id, nome, status]
          properties:
            id: {type: string, format: uuid}
            nome: {type: string}
            status: {type: string}
        technologies:
          type: array
          items:
            $ref: '#/components/schemas/TechnologyOption'
        epics:
          type: array
          items:
            $ref: '#/components/schemas/BacklogEpicNode'

    BacklogEpicNode:
      type: object
      required: [id, titulo, status, tecnologias, features]
      properties:
        id: {type: string, format: uuid}
        titulo: {type: string}
        status: {type: string}
        tecnologias:
          type: array
          items: {$ref: '#/components/schemas/TechnologyOption'}
        features:
          type: array
          items: {$ref: '#/components/schemas/BacklogFeatureNode'}

    BacklogFeatureNode:
      type: object
      required: [id, titulo, status, tecnologias, pbis]
      properties:
        id: {type: string, format: uuid}
        titulo: {type: string}
        status: {type: string}
        tecnologias:
          type: array
          items: {$ref: '#/components/schemas/TechnologyOption'}
        pbis:
          type: array
          items: {$ref: '#/components/schemas/BacklogPbiNode'}

    BacklogPbiNode:
      type: object
      required: [id, codigo, titulo, status, tecnologias]
      properties:
        id: {type: string, format: uuid}
        codigo: {type: string}
        titulo: {type: string}
        status: {type: string}
        tecnologias:
          type: array
          items: {$ref: '#/components/schemas/TechnologyOption'}

    HierarchyArchiveImpact:
      type: object
      required: [epicos, features, pbis]
      properties:
        epicos: {type: integer, minimum: 0}
        features: {type: integer, minimum: 0}
        pbis: {type: integer, minimum: 0}

    ArchiveImpact:
      type: object
      additionalProperties: false
      required: [projeto, epicos, features, pbis]
      properties:
        projeto:
          type: integer
          minimum: 0
          maximum: 1
        epicos:
          type: integer
          minimum: 0
        features:
          type: integer
          minimum: 0
        pbis:
          type: integer
          minimum: 0

    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
          example: usuario@exemplo.com
        password:
          type: string
          format: password
          writeOnly: true

    AuthenticatedUser:
      type: object
      required: [id, nome, email, role]
      properties:
        id:
          type: string
          format: uuid
        nome:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, po, dev]

    AuthUserResponse:
      type: object
      required: [user]
      properties:
        user:
          $ref: '#/components/schemas/AuthenticatedUser'

    CreateProjectRequest:
      type: object
      required: [nome, cliente]
      properties:
        nome:
          type: string
          minLength: 1
          maxLength: 255
        cliente:
          type: string
          minLength: 1
          maxLength: 255
        descricao:
          type: string
          nullable: true
        status:
          type: string
          enum: [ativo, em_andamento, concluido]
          default: ativo
        data_inicio:
          type: string
          format: date-time
          nullable: true

    UpdateProjectRequest:
      type: object
      properties:
        nome:
          type: string
          minLength: 1
          maxLength: 255
        cliente:
          type: string
          minLength: 1
          maxLength: 255
        descricao:
          type: string
          nullable: true
        status:
          type: string
          enum: [ativo, em_andamento, concluido]
        data_inicio:
          type: string
          format: date-time
          nullable: true
        justificativa:
          type: string

    ProjectResponse:
      type: object
      required: [id, nome, cliente, status, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        nome:
          type: string
        cliente:
          type: string
        descricao:
          type: string
          nullable: true
        status:
          type: string
          enum: [ativo, em_andamento, concluido, arquivado]
        data_inicio:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        epicos_count:
          type: integer
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: Data do arquivamento; nula em registros legados sem data conhecida.
        documentos_count:
          type: integer

    PaginatedProjectsResponse:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProjectResponse'
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
        offset:
          type: integer
          minimum: 0

    CreateEpicRequest:
      type: object
      description: Criação sempre em rascunho. Outros valores de status são recusados.
      required: [projeto_id, titulo]
      properties:
        projeto_id:
          type: string
          format: uuid
        titulo:
          type: string
          minLength: 1
          maxLength: 255
        descricao:
          type: string
          nullable: true
        objetivo:
          type: string
          nullable: true
        escopo_macro:
          type: string
          nullable: true
        resultado_esperado:
          type: string
          nullable: true
        prioridade:
          type: string
          enum: [Must, Should, Could]
          default: Must
        tecnologias_ids:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid
          description: IDs do catálogo; associações são substituídas atomicamente. IDs repetidos são normalizados.

    UpdateEpicRequest:
      type: object
      description: Não aceita status. Use os endpoints complete e archive; itens ou ancestrais arquivados são somente leitura.
      properties:
        titulo:
          type: string
          minLength: 1
          maxLength: 255
        descricao:
          type: string
          nullable: true
        objetivo:
          type: string
          nullable: true
        escopo_macro:
          type: string
          nullable: true
        resultado_esperado:
          type: string
          nullable: true
        prioridade:
          type: string
          enum: [Must, Should, Could]
        justificativa:
          type: string
        tecnologias_ids:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid
          description: Quando omitido, preserva as associações atuais; lista vazia remove todas.

    EpicResponse:
      type: object
      description: O estado histórico ativo permite edição. Itens arquivados são preservados apenas para leitura.
      required: [id, projeto_id, titulo, status, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        projeto_id:
          type: string
          format: uuid
        titulo:
          type: string
        descricao:
          type: string
          nullable: true
        objetivo:
          type: string
          nullable: true
        escopo_macro:
          type: string
          nullable: true
        resultado_esperado:
          type: string
          nullable: true
        prioridade:
          type: string
          enum: [Must, Should, Could]
        status:
          type: string
          enum: [rascunho, concluido, ativo, arquivado]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        features_count:
          type: integer
        criterios_count:
          type: integer
        tecnologias_ids:
          type: array
          items:
            type: string
            format: uuid

    PaginatedEpicsResponse:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EpicResponse'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    CreateFeatureRequest:
      type: object
      required: [epico_id, titulo]
      properties:
        epico_id:
          type: string
          format: uuid
        titulo:
          type: string
          minLength: 1
          maxLength: 255
        descricao:
          type: string
          nullable: true
        objetivo:
          type: string
          nullable: true
        prioridade:
          type: string
          enum: [Must, Should, Could]
          default: Must
        tecnologias_ids:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid

    UpdateFeatureRequest:
      type: object
      properties:
        titulo:
          type: string
          minLength: 1
          maxLength: 255
        descricao:
          type: string
          nullable: true
        objetivo:
          type: string
          nullable: true
        prioridade:
          type: string
          enum: [Must, Should, Could]
        justificativa:
          type: string
        tecnologias_ids:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid

    FeatureResponse:
      type: object
      required: [id, epico_id, titulo, status, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        epico_id:
          type: string
          format: uuid
        titulo:
          type: string
        descricao:
          type: string
          nullable: true
        objetivo:
          type: string
          nullable: true
        prioridade:
          type: string
          enum: [Must, Should, Could]
        status:
          type: string
          enum: [rascunho, concluido, arquivado]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        pbis_count:
          type: integer
        criterios_count:
          type: integer
        epico_titulo:
          type: string
        projeto_id:
          type: string
          format: uuid
        tecnologias_ids:
          type: array
          items:
            type: string
            format: uuid

    PaginatedFeaturesResponse:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FeatureResponse'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    CreatePbiRequest:
      type: object
      required: [feature_id, titulo, historia_como_um, historia_eu_quero, historia_para_que]
      properties:
        feature_id:
          type: string
          format: uuid
        titulo:
          type: string
          minLength: 1
          maxLength: 255
        historia_como_um:
          type: string
          minLength: 1
        historia_eu_quero:
          type: string
          minLength: 1
        historia_para_que:
          type: string
          minLength: 1
        regras_observacoes:
          type: string
          nullable: true
        tipo:
          type: string
          default: Funcional
        prioridade:
          type: string
          enum: [Must, Should, Could]
          default: Must
        requer_interface:
          type: boolean
          default: false
          description: Define explicitamente se a verificação de protótipo deve ser aplicada ao PBI.
        tecnologias_ids:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid

    UpdatePbiRequest:
      type: object
      properties:
        titulo:
          type: string
          minLength: 1
          maxLength: 255
        historia_como_um:
          type: string
          minLength: 1
        historia_eu_quero:
          type: string
          minLength: 1
        historia_para_que:
          type: string
          minLength: 1
        regras_observacoes:
          type: string
          nullable: true
        tipo:
          type: string
        prioridade:
          type: string
          enum: [Must, Should, Could]
        requer_interface:
          type: boolean
        justificativa:
          type: string
        tecnologias_ids:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid

    PbiResponse:
      type: object
      required: [id, feature_id, codigo, titulo, historia_como_um, historia_eu_quero, historia_para_que, requer_interface, status, created_at, updated_at]
      properties:
        id:
          type: string
          format: uuid
        feature_id:
          type: string
          format: uuid
        codigo:
          type: string
        titulo:
          type: string
        historia_como_um:
          type: string
        historia_eu_quero:
          type: string
        historia_para_que:
          type: string
        regras_observacoes:
          type: string
          nullable: true
        tipo:
          type: string
        prioridade:
          type: string
          enum: [Must, Should, Could]
        requer_interface:
          type: boolean
          description: Indica se a regra de protótipo é aplicável a este PBI.
        tecnologias_ids:
          type: array
          items:
            type: string
            format: uuid
        prototipo_vinculado:
          type: boolean
          description: Indica se há ao menos um protótipo registrado para este PBI.
        status:
          type: string
          enum: [rascunho, concluido, arquivado]
        score_completude:
          type: integer
        provenance:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        criterios_count:
          type: integer
        feature_titulo:
          type: string
        epico_id:
          type: string
          format: uuid
        epico_titulo:
          type: string
        projeto_id:
          type: string
          format: uuid

    PaginatedPbisResponse:
      type: object
      required: [items, total, limit, offset]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PbiResponse'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    CreateCriterionRequest:
      type: object
      required: [entidade_tipo, entidade_id]
      description: Épico e feature exigem "texto"; PBI exige "nome", "dado", "quando" e "entao" em conjunto.
      properties:
        entidade_tipo:
          type: string
          enum: [epico, feature, pbi]
        entidade_id:
          type: string
          format: uuid
        texto:
          type: string
        nome:
          type: string
        dado:
          type: string
        quando:
          type: string
        entao:
          type: string
        justificativa:
          type: string
          maxLength: 2000

    CriterionResponse:
      type: object
      required: [id, entidade_tipo, entidade_id, ordem, created_at]
      properties:
        id:
          type: string
          format: uuid
        entidade_tipo:
          type: string
          enum: [epico, feature, pbi]
        entidade_id:
          type: string
          format: uuid
        texto:
          type: string
          nullable: true
        nome:
          type: string
          nullable: true
        dado:
          type: string
          nullable: true
        quando:
          type: string
          nullable: true
        entao:
          type: string
          nullable: true
        ordem:
          type: integer
          minimum: 1
        created_at:
          type: string
          format: date-time

    OrganizationVagueTerms:
      type: array
      maxItems: 100
      uniqueItems: true
      description: Termos distintos após normalização Unicode e comparação sem diferenciar maiúsculas
      items: {type: string, minLength: 1, maxLength: 80}
    OrganizationLevelChecks:
      type: object
      additionalProperties: false
      required: [campos_obrigatorios, criterios_aceitacao, termos_vagos]
      properties:
        campos_obrigatorios: {type: boolean}
        criterios_aceitacao: {type: boolean}
        termos_vagos: {type: boolean}
    OrganizationQualityLevels:
      type: object
      additionalProperties: false
      required: [epico, feature, pbi]
      properties:
        epico: {$ref: '#/components/schemas/OrganizationLevelChecks'}
        feature: {$ref: '#/components/schemas/OrganizationLevelChecks'}
        pbi:
          type: object
          additionalProperties: false
          required: [titulo_infinitivo, historia_completa, cenario_estruturado, termos_vagos, prototipo_vinculado]
          properties:
            titulo_infinitivo: {type: boolean}
            historia_completa: {type: boolean}
            cenario_estruturado: {type: boolean}
            termos_vagos: {type: boolean}
            prototipo_vinculado: {type: boolean}
    OrganizationQualityConfiguration:
      type: object
      required: [version, levels, vague_terms, exigir_justificativa_item_concluido, updated_at, updated_by]
      properties:
        version: {type: integer, minimum: 1}
        levels: {$ref: '#/components/schemas/OrganizationQualityLevels'}
        vague_terms: {$ref: '#/components/schemas/OrganizationVagueTerms'}
        exigir_justificativa_item_concluido: {type: boolean}
        updated_at: {type: string, format: date-time}
        updated_by:
          type: object
          nullable: true
          properties:
            id: {type: string, format: uuid, nullable: true, description: Nulo se a conta do autor tiver sido removida}
            nome: {type: string}
    ItemVersion:
      type: object
      required: [id, versao, autor_id, autor_nome, created_at, acao, justificativa]
      properties:
        id: {type: string, format: uuid}
        versao: {type: integer, minimum: 1}
        autor_id: {type: string, format: uuid, nullable: true}
        autor_nome: {type: string, nullable: true}
        created_at: {type: string, format: date-time}
        acao: {type: string}
        justificativa: {type: string, nullable: true}
    ItemVersionSnapshot:
      allOf:
        - {$ref: '#/components/schemas/ItemVersion'}
        - type: object
          required: [snapshot_json]
          properties:
            snapshot_json:
              type: object
              description: Campos da especificação, critérios ordenados e tecnologias na data da versão
              additionalProperties: true
    AuditHistoryItem:
      type: object
      required: [id, entidade_tipo, entidade_id, acao, dados_json, created_at]
      properties:
        id:
          type: string
          format: uuid
        usuario_id:
          type: string
          format: uuid
          nullable: true
        usuario_nome:
          type: string
          nullable: true
        entidade_tipo:
          type: string
          enum: [epico, feature, pbi]
        entidade_id:
          type: string
          format: uuid
        acao:
          type: string
        justificativa:
          type: string
          nullable: true
        dados_json:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        pbi_versao:
          type: integer
          nullable: true
          description: Versão persistida correspondente, quando o evento for uma atualização de PBI.
        pbi_snapshot:
          type: object
          nullable: true
          additionalProperties: true
          description: Snapshot do PBI filtrado para campos permitidos pelo contrato.

    ValidationResultResponse:
      type: object
      required: [aprovado]
      properties:
        aprovado:
          type: boolean
        motivo:
          type: string

    ScenarioQualityResult:
      type: object
      required: [id, aprovado]
      properties:
        id:
          type: string
          format: uuid
        nome:
          type: string
          nullable: true
        aprovado:
          type: boolean
        motivo:
          type: string

    VagueTermOccurrence:
      type: object
      required: [campo, termos]
      properties:
        campo:
          type: string
        termos:
          type: array
          items:
            type: string

    PbiQualityReport:
      type: object
      required: [titulo, historia, cenarios, termos_vagos]
      properties:
        titulo:
          $ref: '#/components/schemas/ValidationResultResponse'
        historia:
          type: object
          required: [aprovado, alertas]
          properties:
            aprovado:
              type: boolean
            alertas:
              type: array
              items:
                type: string
        cenarios:
          type: array
          items:
            $ref: '#/components/schemas/ScenarioQualityResult'
        termos_vagos:
          type: array
          items:
            $ref: '#/components/schemas/VagueTermOccurrence'

    PbiCompletenessReport:
      type: object
      required: [entity_type, entity_id, rule_version, checks, score_completude]
      properties:
        entity_type:
          type: string
          enum: [pbi]
        entity_id:
          type: string
          format: uuid
        rule_version:
          type: string
          description: Versão do conjunto atual de verificações considerado no cálculo.
        checks:
          type: array
          items:
            type: object
            required: [check_id, check_name, passed, message, applicable]
            properties:
              check_id:
                type: string
              check_name:
                type: string
              passed:
                type: boolean
              message:
                type: string
              applicable:
                type: boolean
                enum: [true]
        score_completude:
          type: integer
          minimum: 0
          maximum: 100
          nullable: true

    PbiQualityConfigurationInput:
      type: object
      additionalProperties: false
      required: [checks, vague_terms]
      properties:
        checks:
          type: object
          additionalProperties: false
          required: [titulo_infinitivo, historia_completa, cenario_estruturado, termos_vagos, prototipo_vinculado]
          properties:
            titulo_infinitivo: { type: boolean }
            historia_completa: { type: boolean }
            cenario_estruturado: { type: boolean }
            termos_vagos: { type: boolean }
            prototipo_vinculado: { type: boolean }
        vague_terms:
          type: array
          maxItems: 100
          items: { type: string, minLength: 1, maxLength: 80 }
        exigir_justificativa_item_concluido:
          type: boolean
          description: Se alterações em itens concluídos exigem justificativa; omissão preserva a configuração atual.

    PbiQualityConfiguration:
      allOf:
        - $ref: '#/components/schemas/PbiQualityConfigurationInput'
        - type: object
          required: [rule_version, updated_at, updated_by, exigir_justificativa_item_concluido]
          properties:
            rule_version: { type: string, example: pbi-quality-v2 }
            updated_at: { type: string, format: date-time }
            updated_by:
              type: object
              nullable: true
              required: [id, nome]
              properties:
                id: { type: string, format: uuid }
                nome: { type: string }

    DecisionNode:
      type: object
      required: [tipo, id, titulo]
      properties:
        tipo: {type: string, enum: [projeto, epico, feature, pbi]}
        id: {type: string, format: uuid}
        titulo: {type: string}
        codigo: {type: string, nullable: true}

    DecisionInput:
      type: object
      additionalProperties: false
      required: [titulo, contexto, decisao, justificativa]
      properties:
        titulo: {type: string, minLength: 3, maxLength: 255}
        contexto: {type: string, minLength: 1, maxLength: 5000}
        decisao: {type: string, minLength: 1, maxLength: 5000}
        justificativa: {type: string, minLength: 1, maxLength: 5000}
        alternativas: {type: string, nullable: true, maxLength: 5000}

    Decision:
      type: object
      required: [id, titulo, contexto, decisao, justificativa, created_at, origem]
      properties:
        id: {type: string, format: uuid}
        titulo: {type: string}
        contexto: {type: string}
        decisao: {type: string}
        justificativa: {type: string}
        alternativas: {type: string, nullable: true}
        autor:
          type: object
          nullable: true
          properties:
            id: {type: string, format: uuid}
            nome: {type: string}
        created_at: {type: string, format: date-time}
        origem:
          allOf:
            - $ref: '#/components/schemas/DecisionNode'
            - type: object
              required: [herdada]
              properties:
                herdada: {type: boolean}

    DecisionList:
      type: object
      required: [entidade, ancestrais, decisoes]
      properties:
        entidade:
          $ref: '#/components/schemas/DecisionNode'
        ancestrais:
          type: array
          items:
            $ref: '#/components/schemas/DecisionNode'
        decisoes:
          type: array
          items:
            $ref: '#/components/schemas/Decision'

    SuggestionInput:
      type: object
      additionalProperties: false
      required: [campo, valor_sugerido]
      properties:
        campo: {type: string, description: Nome do campo sugerível do item (varia por tipo de entidade)}
        valor_sugerido: {type: string, minLength: 1}
        origem: {type: string, description: Origem da proposta (ex. harness-pro4tech); default manual}

    ResolveAcceptInput:
      type: object
      additionalProperties: false
      properties:
        justificativa: {type: string, description: Obrigatória apenas quando o item já está concluído}

    ResolveEditInput:
      type: object
      additionalProperties: false
      required: [valor]
      properties:
        valor: {type: string, minLength: 1}
        justificativa: {type: string, description: Obrigatória apenas quando o item já está concluído}

    Suggestion:
      type: object
      required: [id, entidade_tipo, entidade_id, campo, valor_sugerido, origem, status, created_at, updated_at]
      properties:
        id: {type: string, format: uuid}
        entidade_tipo: {type: string, enum: [epico, feature, pbi]}
        entidade_id: {type: string, format: uuid}
        campo: {type: string}
        valor_sugerido: {type: string}
        valor_resolvido: {type: string, nullable: true}
        origem: {type: string}
        status: {type: string, enum: [pendente, aceita, editada, descartada]}
        criado_por: {type: string, format: uuid, nullable: true}
        criado_por_nome: {type: string, nullable: true}
        resolvido_por: {type: string, format: uuid, nullable: true}
        resolvido_por_nome: {type: string, nullable: true}
        resolvido_em: {type: string, format: date-time, nullable: true}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}

    SimilarItemsSearchInput:
      type: object
      additionalProperties: false
      required: [tipo]
      properties:
        tipo: {type: string, enum: [epico, feature, pbi]}
        titulo: {type: string, maxLength: 255}
        descricao: {type: string, maxLength: 5000}
        excluir_id: {type: string, format: uuid, description: Item já salvo que está em edição (não é sugerido a si mesmo)}

    SimilarItem:
      type: object
      required: [tipo, id, titulo, status, similaridade, trecho, projeto, outro_projeto, caminho, origem, ja_aproveitado]
      properties:
        tipo: {type: string, enum: [epico, feature, pbi]}
        id: {type: string, format: uuid}
        codigo: {type: string, nullable: true}
        titulo: {type: string}
        status: {type: string}
        similaridade: {type: number, minimum: 0, maximum: 1}
        trecho: {type: string}
        projeto:
          type: object
          required: [id, nome]
          properties:
            id: {type: string, format: uuid}
            nome: {type: string}
        outro_projeto: {type: boolean, description: true quando o item pertence a outro projeto}
        caminho:
          type: array
          items:
            type: object
            required: [tipo, id, titulo]
            properties:
              tipo: {type: string, enum: [epico, feature, pbi]}
              id: {type: string, format: uuid}
              titulo: {type: string}
        origem: {type: string, description: 'Rótulo legível, ex. Projeto › Épico › Feature'}
        ja_aproveitado: {type: boolean}

    SimilarItemsResult:
      type: object
      required: [items, total, degradado]
      properties:
        items:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/SimilarItem'
        total: {type: integer}
        degradado: {type: boolean, description: true quando o serviço de embeddings estava indisponível}

    SimilarItemsReuseInput:
      type: object
      additionalProperties: false
      properties:
        campos:
          type: array
          minItems: 1
          items: {type: string}
          description: Campos a copiar (padrão todos os campos de texto sugeríveis com conteúdo)

    SimilarItemsReuseResult:
      type: object
      required: [relacao, sugestoes]
      properties:
        relacao:
          type: object
          required: [id, tipo_relacao, destino_tipo, destino_id, origem_tipo, origem_id, origem_projeto_id, campos]
          properties:
            id: {type: string, format: uuid}
            tipo_relacao: {type: string, enum: [reaproveitado_de]}
            destino_tipo: {type: string, enum: [epico, feature, pbi]}
            destino_id: {type: string, format: uuid}
            destino_projeto_id: {type: string, format: uuid}
            origem_tipo: {type: string, enum: [epico, feature, pbi]}
            origem_id: {type: string, format: uuid}
            origem_projeto_id: {type: string, format: uuid}
            campos: {type: array, items: {type: string}}
            criado_por: {type: string, format: uuid, nullable: true}
            created_at: {type: string}
            updated_at: {type: string}
        sugestoes:
          type: array
          items:
            $ref: '#/components/schemas/Suggestion'

    SuggestionList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Suggestion'

    BacklogSearchResponse:
      type: object
      required: [projeto_id, termo, total, limite, items]
      properties:
        projeto_id: {type: string, format: uuid}
        termo: {type: string}
        total: {type: integer, minimum: 0, description: Total de correspondências (pode exceder items)}
        limite: {type: integer}
        items:
          type: array
          items:
            type: object
            required: [tipo, id, titulo, status, campo, trecho, caminho, tecnologias]
            properties:
              tipo: {type: string, enum: [epico, feature, pbi]}
              id: {type: string, format: uuid}
              titulo: {type: string}
              codigo: {type: string, nullable: true}
              status: {type: string}
              campo: {type: string, enum: [titulo, descricao]}
              trecho:
                type: object
                required: [texto, destaques]
                properties:
                  texto: {type: string}
                  destaques:
                    type: array
                    description: Faixas [inicio, fim) em unidades UTF-16 de `texto`
                    items:
                      type: array
                      minItems: 2
                      maxItems: 2
                      items: {type: integer}
              caminho:
                type: array
                description: Épico → Feature → PBI até o nível do item
                items:
                  type: object
                  required: [tipo, id, titulo]
                  properties:
                    tipo: {type: string, enum: [epico, feature, pbi]}
                    id: {type: string, format: uuid}
                    titulo: {type: string}
                    codigo: {type: string, nullable: true}
              tecnologias:
                type: array
                items:
                  type: object
                  properties:
                    id: {type: string, format: uuid}
                    nome: {type: string}

    ProjectDocument:
      type: object
      required: [id, projeto_id, nome, status_processamento, created_at]
      properties:
        id: { type: string, format: uuid }
        projeto_id: { type: string, format: uuid }
        nome: { type: string, maxLength: 255 }
        extensao: { type: string, nullable: true, enum: [.pdf, .docx, .md, .txt] }
        mime: { type: string, nullable: true }
        tamanho_bytes: { type: integer, nullable: true, minimum: 1 }
        status_processamento:
          type: string
          description: Estado durável do pipeline de extração e indexação assíncrona (S2-01/S2-02)
          enum: [pendente, processando, processado, falha]
        processamento_erro: {type: string, nullable: true, maxLength: 300}
        processamento_tentativas: {type: integer, minimum: 0}
        armazenamento_pendente:
          type: boolean
          description: true enquanto a finalização do arquivo local ainda é reconciliada pelo worker
        autor_id: { type: string, format: uuid, nullable: true }
        autor_nome: { type: string, nullable: true }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    DocumentLimits:
      type: object
      required: [max_bytes, extensoes_permitidas]
      properties:
        max_bytes: { type: integer, minimum: 1 }
        extensoes_permitidas:
          type: array
          items: { type: string }

    DocumentList:
      type: object
      required: [items, next_cursor, limites, paginacao]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProjectDocument'
        next_cursor:
          type: string
          nullable: true
        limites:
          $ref: '#/components/schemas/DocumentLimits'
        paginacao:
          type: object
          required: [tamanho_pagina, tamanho_maximo]
          properties:
            tamanho_pagina: {type: integer}
            tamanho_maximo: {type: integer}

    DocumentRemovedEvent:
      type: object
      additionalProperties: false
      required: [event_id, event_type, schema_version, occurred_at, project_id, document_id, chunks_removed]
      properties:
        event_id:
          type: string
          description: Chave estável por documento, no formato document.removed:{document_id}
        event_type:
          type: string
          enum: [document.removed]
        schema_version:
          type: integer
          enum: [1]
        occurred_at: { type: string, format: date-time }
        project_id: { type: string, format: uuid }
        document_id: { type: string, format: uuid }
        chunks_removed: { type: integer, minimum: 0 }

    IngestDocumentRequest:
      type: object
      required: [document_id, text_content]
      properties:
        document_id:
          type: string
        text_content:
          type: string
        project_id:
          type: string
          format: uuid
          nullable: true
        metadata:
          type: object
          additionalProperties: true

    IngestDocumentResponse:
      type: object
      required: [document_id, total_chunks, status, chunks]
      properties:
        document_id:
          type: string
        total_chunks:
          type: integer
          minimum: 0
        status:
          type: string
          enum: [chunked_and_indexed]
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/ProcessedChunk'

    ProcessedChunk:
      type: object
      required: [chunk_index, text, vector_dimension]
      properties:
        chunk_index:
          type: integer
          minimum: 0
        text:
          type: string
        vector_dimension:
          type: integer
          minimum: 0
        project_id:
          type: string
          format: uuid
          nullable: true

    IngestEntityRequest:
      type: object
      required: [entity_type, data]
      properties:
        entity_type:
          type: string
          enum: [epic, feature, pbi, decision]
        data:
          type: object
          additionalProperties: true

    EmbeddingRequest:
      type: object
      required: [text]
      properties:
        text:
          type: string
          minLength: 1
        model:
          type: string
          nullable: true

    RagQueryRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
        project_id:
          type: string
          format: uuid
          nullable: true
        context_chunks:
          type: array
          items:
            type: string

    HybridSearchResponse:
      type: object
      required: [items, total, query, project_id, filters, metrics]
      properties:
        items:
          type: array
          items:
            type: object
            required: [id, project_id, project_name, entity_type, entity_id, text, metadata, relevance_score]
            properties:
              id: {type: string, format: uuid, description: ID estável do chunk para avaliação de busca}
              project_id: {type: string, format: uuid}
              project_name: {type: string}
              entity_type: {type: string, enum: [documento, decisao, epico, feature, pbi, analise_repositorio]}
              entity_id: {type: string, format: uuid}
              title: {type: string, nullable: true}
              text: {type: string}
              metadata: {type: object, additionalProperties: true}
              source_url: {type: string, nullable: true}
              relevance_score: {type: number}
        total: {type: integer}
        query: {type: string}
        project_id: {type: string, format: uuid}
        filters:
          type: object
          required: [technology_id, level]
          properties:
            technology_id: {type: string, format: uuid, nullable: true}
            level: {type: string, enum: [documento, decisao, epico, feature, pbi, analise_repositorio], nullable: true}
        metrics:
          type: object
          required: [latency_ms]
          properties:
            latency_ms: {type: integer, minimum: 0}

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
        code:
          type: string
        correlation_id:
          type: string
          format: uuid
        details:
          type: object
          additionalProperties: true

  responses:
    ValidationError:
      description: Corpo inválido ou campo obrigatório ausente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Autenticação ausente, sessão inválida ou sessão expirada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'