Validação de Regras de Negócio

​

Visão geral

Kody · Business Logic #291 · Ticket SLA badge — Para corrigir: 2 requisitos faltando

	Requisito	Neste PR
✅ MET	O cabeçalho do ticket mostra um badge com o tempo de SLA restante.	TicketPanel.tsx:40 · O badge aparece no cabeçalho como “SLA Xh Ym”.
❌ MISSING	O badge fica vermelho quando falta menos de 1 hora.	SlaBadge.tsx:14 · O badge sempre usa o tom “info”. Do: trocar para o tom de perigo abaixo de 60 minutos.
❌ MISSING	Tickets resolvidos não mostram badge.	TicketPanel.tsx:40 · Aparece qualquer que seja o status. Do: esconder quando o ticket está resolvido.

​

Pré-requisitos

• Um gerenciador de tarefas conectado em Plugins: Linear, Jira (Atlassian Rovo), Notion, Git Issues ou um plugin customizado.
• Kody só lê tarefas pelo id, e o que elas referenciam (uma tarefa pai, sub-tarefas, documentos anexados). Ele nunca busca tarefas nem escreve no seu gerenciador.
• Sem gerenciador, você ainda pode colar o texto da tarefa no comando (veja abaixo).

​

Como ligar

reviewOptions:
  business_logic: true

​

Como Kody encontra a tarefa

• Chaves como PROJ-123 (Jira, Linear e a maioria dos gerenciadores)
• #123 e owner/repo#123 (issues do Git; um número que é um pull request é ignorado)
• AB#123 (Azure Boards)
• Links para Linear, Jira, Notion, issues do GitHub/GitLab e work items do Azure

• Uma tarefa pai (uma sub-issue do Linear, uma sub-task do Jira, uma subtask do ClickUp): o PR é conferido contra os requisitos da tarefa pai que o título desta tarefa cobre. Uma sub-issue que diz “veja a tarefa pai” ainda é conferida.
• Sub-tarefas: um requisito que uma delas entrega aparece como CHECK MANUALLY (“Delivered by KOD-20”), nunca como faltando.
• Documentos anexados à tarefa (docs do Linear): lidos como parte da tarefa, critérios incluídos.

​

Como o PR cita a tarefa

• “Closes PROJ-1” ou uma chave no título ou na branch: o PR é conferido contra a tarefa inteira.
• “Part of PROJ-1”: o PR entrega uma parte. O que falta é listado, mas não como algo a resolver antes do merge.
• “Refs PROJ-1”, “see PROJ-1” ou “related to PROJ-1” na descrição: uma menção. Só é conferida quando o PR não cita outra tarefa, e aí como a tarefa do próprio PR.
• Até três tarefas são conferidas por PR, uma seção para cada. Um PR que referencia mais (um release ou um merge) é pulado.

​

Os cinco estados

​

Antes de um gap aparecer

• O requisito como a tarefa escreve. Uma entrada ou caso extremo que a tarefa nunca cita (valores negativos, outro caminho do código, um formato que ela não menciona) nunca deixa uma linha PARTIAL, e o que acontece depois da mudança também não (que um job existente envia a mensagem que o PR enfileira, que uma rota usa o serializer que o PR preenche).
• O código que o PR chama, não só o diff. Quando uma regra mora num código que o PR chama mas não alterou (um validador, um helper, o mapper que monta uma resposta), Kody lê esse código no repositório, no head do PR, antes de mostrar qualquer coisa, e faz o mesmo para toda linha MISSING, PARTIAL e CHECK MANUALLY. Uma linha só vira MET com um arquivo e uma linha que Kody leu, e diz que já está no código, fora do diff. Uma linha só vira MISSING quando Kody leu o código de que o PR depende e cita a linha em que falta a regra. O que o repositório não decide fica como estava.
• Trabalho que pertence a outro lugar. Um requisito que uma sub-tarefa entrega, ou que a orientação do seu time diz que não é conferido aqui, fica CHECK MANUALLY e nunca é julgado de novo como faltando.

​

No pull request

• Kody confere o PR na primeira revisão. Depois disso, confere de novo quando alguém comenta @kody -v business-logic ou roda @kody review --force. Re-check também pode ser a cada push enquanto algo estiver faltando, para uma correção atualizar o comentário sem ninguém pedir, ou a cada push; cada um é mais uma validação por push.
• Confira de novo quando quiser com @kody -v business-logic. O mesmo comentário é editado; Kody nunca posta um segundo.
• Um PR que cumpre a tarefa recebe um comentário de uma linha (”✅ 4 of 4 met”), mais o que houver para conferir manualmente, para o autor saber que foi conferido. Desligue Comment when every requirement is met para não comentar nesses casos.
• O comentário é o sinal em todas as plataformas: Kody não escreve check nem status, então nunca bloqueia um merge sozinho. O cabeçalho diz o que falta corrigir.

​

Respondendo ao comentário

• Discordar: “Está coberto em useDrag.ts”. Kody confere de novo o que você apontou e marca como MET ou diz o que olhou e mantém.
• Aceitar um apontamento (alguém que não é o autor do PR: no GitHub, com permissão de escrita no repositório; no GitLab, Developer ou acima no repositório; no Bitbucket, Azure Repos e Forgejo, um membro da organização que a plataforma lista): “Reordenar pelo teclado está fora do escopo, foi para SAA-102”. Kody confirma que SAA-102 existe, marca a linha como ACCEPTED com quem aceitou, e ela deixa de ficar pendente. A decisão se mantém nas próximas conferências, mesmo quando Kody escreve o requisito de um jeito um pouco diferente, enquanto o texto da tarefa não mudar; se a tarefa for editada, o requisito precisa ser aceito de novo.

​

Quando Kody fica em silêncio

​

Rodando sob demanda

• @kody -v business-logic: confere de novo as tarefas que o PR referencia
• @kody -v business-logic PROJ-123 ou um link de tarefa: confere contra essa tarefa
• @kody -v business-logic seguido dos requisitos em texto: confere contra o que você escreveu, sem precisar de gerenciador

​

Configurações

• Task source: todos os gerenciadores conectados (plugins de tarefa customizados como o ClickUp incluídos), ou um plugin. Para um plugin customizado, escolha a ferramenta que lê uma tarefa pelo id; só ferramentas de leitura são oferecidas. Use Try it, fixo à direita da página (precisa de permissão para editar essas configurações): uma tarefa sozinha mostra o que Kody lê dela, e um pull request roda a conferência inteira sem postar, com as configurações da tela, salvas ou não. Post to the pull request posta o resultado mostrado, sem rodar de novo, uma vez por teste; é recusado se o pull request recebeu um commit depois do teste, então rode o teste de novo antes.
• Custom task id format (opcional): uma expressão regular para ids que Kody não encontra sozinho: T(\d{4}) lê T1234 como a tarefa 1234. Chaves como SAA-96, #12, AB#8, CU-… e links de gerenciadores são encontrados sem ela, assim como uma chave em minúsculas como sc-123 no nome da branch. No título ou na descrição, uma chave em minúsculas só conta quando o Linear ou o Jira tem aquele time ou projeto; para outro gerenciador, defina o formato. Um número que o formato captura só é lido como issue do Git quando Git Issues é a fonte de tarefas; com todos os gerenciadores conectados, T1234 nunca vira a issue #1234 do repositório.
• Where acceptance criteria live: detectado automaticamente (um campo de critérios, um checklist ou uma lista na descrição), sob um título na descrição, ou num campo customizado; uma tarefa sem o campo é lida pela descrição. Com Under a heading em Acceptance criteria, esta tarefa é conferida contra os três itens, e o parágrafo acima é contexto:
  Agents should see at a glance how much time is left on a ticket's SLA.
  
  ## Acceptance criteria
  - The ticket header shows a badge with the remaining SLA time.
  - The badge turns red when less than 1 hour is left.
  - Resolved tickets show no badge.
  
• Comment when every requirement is met (ligado por padrão): um PR que entrega a tarefa recebe um comentário de uma linha. Desligado, não recebe nenhum; as lacunas continuam sendo postadas.
• Ask for a task when the PR references none: Kody comenta perguntando qual é a tarefa do PR (ou apontando o erro de digitação), em vez de pular. PRs abertos por bots, como Dependabot ou Renovate, ficam de fora. Um gerenciador fora do ar nunca conta.
• Re-check: só sob demanda (padrão), a cada push enquanto algo estiver faltando, ou a cada push. Cada conferência usa o modelo da sua organização, como um review, então a cada push custa uma validação por push.
• Pull requests pulados: os que o code review pula são pulados aqui também: títulos com uma palavra ignorada (ignoredTitleKeywords, como wip) e drafts quando runOnDraft está desligado. Um comentário @kody -v business-logic sempre roda.
• Team guidance: notas que Kody segue ao julgar, por exemplo “Feature flags contam como implementadas quando a flag existe e vem desligada”. Ela não muda o formato do veredito nem faz Kody inventar requisitos.

​

Combinações comuns

businessLogic:
  taskSource: 'auto'              # ou o integration id de um plugin
  taskSourceTool: 'get_ticket'    # só plugin customizado: a ferramenta que lê uma tarefa pelo id
  taskIdPattern: 'T(\d{4})'       # opcional: ids que o Kody não acha sozinho
  criteriaLocation: 'heading'     # auto | heading | field
  criteriaHeading: 'Acceptance criteria'
  # criteriaField: 'Acceptance Criteria'   # com criteriaLocation: 'field'
  teamGuidance: 'Feature flags count as implemented when the flag exists and defaults to off.'
  commentWhenMet: true
  recheckOn: 'request'            # request | failing | push
  requireTask: false

​

Pela CLI

kodus pr business-validation --task-id AB#8
kodus pr business-validation --task-id AB#8 --format json

​

Cockpit