Validación de Lógica de Negocio

​

Descripción General

Kody · Business Logic #291 · Ticket SLA badge — Por corregir: 2 requisitos faltantes

	Requisito	En este PR
✅ MET	El encabezado del ticket muestra un badge con el tiempo de SLA restante.	TicketPanel.tsx:40 · El badge se muestra en el encabezado como “SLA Xh Ym”.
❌ MISSING	El badge se vuelve rojo cuando queda menos de 1 hora.	SlaBadge.tsx:14 · El badge siempre usa el tono “info”. Do: pasar al tono de peligro por debajo de 60 minutos.
❌ MISSING	Los tickets resueltos no muestran badge.	TicketPanel.tsx:40 · Se muestra sea cual sea el estado. Do: ocultarlo cuando el ticket está resuelto.

​

Requisitos previos

• Un gestor de tareas conectado en Plugins: Linear, Jira (Atlassian Rovo), Notion, Git Issues o un plugin personalizado.
• Kody solo lee tareas por su id, y lo que enlazan (una tarea padre, subtareas, documentos adjuntos). Nunca busca tareas ni escribe en tu gestor.
• Sin un gestor, puedes pegar el texto de la tarea en el comando (ver más abajo).

​

Activarla

reviewOptions:
  business_logic: true

​

Cómo encuentra Kody la tarea

• Claves como PROJ-123 (Jira, Linear y la mayoría de los gestores)
• #123 y owner/repo#123 (Git issues; un número que corresponde a un pull request se ignora)
• AB#123 (Azure Boards)
• Enlaces a Linear, Jira, Notion, issues de GitHub/GitLab y work items de Azure

• Una tarea padre (un sub-issue de Linear, una subtarea de Jira, una subtarea de ClickUp): el PR se compara con los requisitos del padre que cubre el título de esta tarea. Un sub-issue que dice “ver el padre” también se comprueba.
• Subtareas: un requisito que entrega una de ellas aparece como CHECK MANUALLY (“Delivered by KOD-20”), nunca como faltante.
• Documentos adjuntos a la tarea (docs de Linear): se leen como parte de la tarea, criterios incluidos.

​

Cómo el PR nombra la tarea

• “Closes PROJ-1” o una clave en el título o la rama: el PR se compara con la tarea completa.
• “Part of PROJ-1”: el PR entrega una parte. Lo que falta se lista, pero no como algo pendiente para el merge.
• “Refs PROJ-1”, “see PROJ-1” o “related to PROJ-1” en la descripción: una mención. Solo se comprueba cuando el PR no nombra otra tarea, y entonces como la tarea del propio PR.
• Hasta tres tareas se comprueban por PR, una sección por cada una. Un PR que menciona más (una release o un merge) se omite.

​

Los cinco estados

​

Antes de mostrar una brecha

• El requisito tal como lo escribe la tarea. Una entrada o un caso límite que la tarea nunca menciona (importes negativos, otra ruta de código, un formato que no menciona) nunca hace que una fila sea PARTIAL, y tampoco lo que ocurre después del cambio (que un job existente envíe el mensaje que el PR pone en cola, que una ruta use el serializador que el PR completa).
• El código que llama el PR, no solo el diff. Cuando una regla vive en código que el PR llama pero no modificó (un validador, un helper, el mapper que construye una respuesta), Kody lo lee en el repositorio en el head del PR antes de mostrar nada, y hace lo mismo con cada fila MISSING, PARTIAL y CHECK MANUALLY. Una fila pasa a MET solo con un archivo y una línea que Kody leyó, e indica que ya está en el código, fuera del diff. Una fila pasa a MISSING solo cuando Kody leyó el código del que depende el PR y cita la línea a la que le falta la regla. Lo que el repositorio no resuelve se queda como estaba.
• Trabajo que corresponde a otro lugar. Un requisito que entrega una subtarea, o uno que las indicaciones de tu equipo dicen que no se comprueba aquí, se queda en CHECK MANUALLY y nunca se vuelve a juzgar como faltante.

​

En el pull request

• Kody comprueba el PR en su primera revisión. Después, vuelve a comprobarlo cuando alguien comenta @kody -v business-logic o ejecuta @kody review --force. Re-check también se puede configurar para cada push mientras falte algo, para que una corrección actualice el comentario sin que nadie lo pida, o para cada push; cada opción suma una validación por push.
• Vuelve a comprobar en cualquier momento con @kody -v business-logic. Se edita el mismo comentario; Kody nunca publica un segundo.
• Un PR que cumple su tarea recibe un comentario de una línea (”✅ 4 of 4 met”), más lo que haya que comprobar a mano, para que el autor sepa que se comprobó. Desactiva Comment when every requirement is met para no comentar en esos casos.
• El comentario es la señal en todas las plataformas: Kody no escribe un check ni un status, así que nunca bloquea un merge por sí solo. Su encabezado dice lo que queda por corregir.

​

Responder al comentario

• Discrepar: “Está cubierto en useDrag.ts”. Kody vuelve a comprobar lo que señalaste y lo marca como MET o dice qué revisó y lo mantiene.
• Aceptar un hallazgo (alguien que no es el autor del PR: en GitHub, con permiso de escritura en el repositorio; en GitLab, Developer o superior en el repositorio; en Bitbucket, Azure Repos y Forgejo, un miembro de la organización que la plataforma lista): “El reordenamiento con teclado está fuera del alcance, movido a SAA-102”. Kody confirma que SAA-102 existe, marca la fila como ACCEPTED con quién la aceptó, y deja de estar pendiente de corregir. La decisión se mantiene en las comprobaciones posteriores, aunque Kody redacte el requisito de forma un poco distinta, mientras el texto de la tarea no cambie; si la tarea se edita, hay que aceptar el requisito de nuevo.

​

Cuándo Kody no comenta

​

Ejecución bajo demanda

• @kody -v business-logic: vuelve a comprobar las tareas que referencia el PR
• @kody -v business-logic PROJ-123 o un enlace a una tarea: compara con esa tarea
• @kody -v business-logic seguido de los requisitos en texto: compara con lo que escribiste, sin necesidad de gestor

​

Configuración

• Task source: todos los gestores conectados (plugins de tareas personalizados como ClickUp incluidos), o un solo plugin. Para un plugin personalizado, elige la herramienta que lee una tarea por su id; solo se ofrecen herramientas de solo lectura. Usa Try it, fijo a la derecha de la página (necesita permiso para editar esta configuración): una tarea sola muestra lo que Kody lee de ella, y un pull request ejecuta la comprobación completa sin publicar, con la configuración que hay en pantalla, guardada o no. Post to the pull request publica el resultado mostrado, sin ejecutarlo de nuevo, una vez por prueba; se rechaza si el pull request recibió un commit después de la prueba, así que vuelve a ejecutarla primero.
• Custom task id format (opcional): una expresión regular para ids que Kody no encuentra por sí solo: T(\d{4}) lee T1234 como la tarea 1234. Claves como SAA-96, #12, AB#8, CU-… y los enlaces de gestores se encuentran sin ella, igual que una clave en minúsculas como sc-123 en el nombre de una rama. En un título o una descripción, una clave en minúsculas solo cuenta cuando Linear o Jira tienen ese equipo o proyecto; para otro gestor, define el formato. Un número que el formato captura solo se lee como issue de Git cuando Git Issues es la fuente de tareas; con todos los gestores conectados, T1234 nunca es la issue #1234 del repositorio.
• Where acceptance criteria live: detectado automáticamente (un campo de criterios, un checklist o una lista en la descripción), bajo un encabezado en la descripción, o en un campo personalizado; una tarea sin ese campo se lee desde su descripción. Con Under a heading en Acceptance criteria, esta tarea se compara con sus tres viñetas, y el párrafo de arriba es 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 (activado por defecto): un PR que cumple su tarea recibe un comentario de una línea. Desactivado, no recibe ninguno; los huecos se publican igual.
• Ask for a task when the PR references none: Kody comenta preguntando para qué tarea es el PR (o señalando el error tipográfico), en lugar de omitirlo. Los PRs abiertos por bots, como Dependabot o Renovate, se dejan en paz. Un gestor caído nunca cuenta.
• Re-check: solo a petición (por defecto), en cada push mientras falte algo, o en cada push. Cada verificación usa el modelo de tu organización, como una revisión, así que en cada push cuesta una validación por push.
• Skipped pull requests: los que omite la revisión de código también se omiten aquí: títulos con una palabra clave ignorada (ignoredTitleKeywords, como wip) y borradores cuando runOnDraft está desactivado. Un comentario @kody -v business-logic siempre se ejecuta.
• Team guidance: notas que Kody sigue al juzgar, por ejemplo “Los feature flags cuentan como implementados cuando el flag existe y está desactivado por defecto”. No pueden cambiar el formato del veredicto ni hacer que Kody invente requisitos.

​

Configuraciones comunes

businessLogic:
  taskSource: 'auto'              # o el integration id de un plugin
  taskSourceTool: 'get_ticket'    # solo plugin personalizado: la herramienta que lee una tarea por id
  taskIdPattern: 'T(\d{4})'       # opcional: ids que Kody no encuentra solo
  criteriaLocation: 'heading'     # auto | heading | field
  criteriaHeading: 'Acceptance criteria'
  # criteriaField: 'Acceptance Criteria'   # con 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

​

Desde la CLI

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

​

Cockpit