El PR se revisa sin clonar

La descripción completa, aunque no quepa

Azure DevOps corta la descripción de un Pull Request en 4.000 caracteres (contados en UTF-16). Desde 3.153.0 lo que no entra va a los comentarios del PR: el corte cae entre bloques —nunca a mitad de una tabla o de una URL—, cada parte lleva su marca y en la ronda siguiente se edita en vez de duplicarse. Y los enlaces a las evidencias van con %20 en vez de +: un nombre de archivo con espacios abría un archivo que no existe.

El cuerpo del Pull Request nombraba la ruta física del expediente (C:/…/Documentacion/…), y eso obligaba al revisor a clonar el repositorio de documentación y abrir un visor de markdown para ver una captura. El efecto real no era incomodidad:

Una evidencia que cuesta clonar un repositorio no se revisa — se aprueba sin mirar. Y ahí se corta toda la trazabilidad que el framework construyó antes.

La hoja de aprobación

kb pr arma un Pull Request por repositorio, y su cuerpo se lee en el orden en que lo lee el revisor:

1. Qué cambia — el primer párrafo que redactó el agente, en dos o tres líneas.
2. El riesgo del merge — dónde gastar el tiempo de la revisión, calculado del diff: la puerta (de una vía si trae algo que un revert no deshace, de dos vías si no) y el radio de impacto (hasta dónde llega y quién consume lo que cambia).
3. Un renglón con el repositorio, sus componentes, las tareas cerradas y los enlaces al expediente.
4. Una sola tabla de evidencia, con una columna por componente del repositorio: qué exige la ficha de cada uno y cómo salió, con el veredicto leído del propio archivo — una corrida en rojo sale en rojo — y el enlace directo a ese archivo.
5. Las capturas de las E2E, agrupadas por caso, y el árbol de lo que tocó la rama.
6. El resto de lo que redactó el agente: el detalle técnico y cómo probarlo.

**Qué cambia:** Registra los incidentes regulatorios desde la pantalla.

**Riesgo del merge:** puerta de **dos vías** — nada en el diff que un revert no deshaga; cambia el esquema o los datos sin borrar ni sobrescribir nada: se revierte con su script de rollback.
**Radio de impacto:** **aplicación** — 14 archivo(s) en OPS-WEB, OPS-API; dependen de lo que cambia: OPS-REPORTES (inventario y `kb mapa`).

**Repositorio** `ops-app` · **componentes** `OPS-WEB`, `OPS-API` · **tareas** 6/6 · 📁 Evidencias · 📄 Expediente

| Evidencia                  | `OPS-WEB` | `OPS-API`   |
|----------------------------|:---------:|:-----------:|
| E01 Compilación sin errores| ✅ ver    | ✅ ver      |
| E03 Pruebas unitarias      | ✅ ver    | ❌ falló    |
| E04 Pruebas E2E            | ✅ ver    | ✅ ver      |
| E05 Pantalla funcionando   | ✅ ver    | no se exige |

El riesgo lo calcula kbspec, no el agente. Las señales de una puerta de una vía son DROP TABLE o DROP COLUMN, TRUNCATE, DELETE, un UPDATE o un MERGE que sobrescriben, ALTER COLUMN, un renombre, una migración que borra en su Up, un envío de correos o a una cola, y el expediente que lo declara irreversible. Cada una sale con su archivo y su línea, y al lado el estado del rollback: el plan del 08 y el script de la E06. Solo cuenta lo que corre al desplegar —el cuerpo de un procedimiento es lógica de la aplicación, el Down de una migración es su rollback—, y solo lo que la rama agregó o cambió. Una puerta de una vía sin rollback avisa, no frena: el 08 se escribe después del PR.

La exigencia se declara por componente: al frontend se le piden E2E y la pantalla, a un proyecto de base de datos sus scripts. Lo que la ficha de un componente no pide dice «no se exige». Y la evidencia de un componente no cuenta por la de otro: cada uno busca la suya por el sufijo con que kb pruebas la escribe.

kb hoja            # qué falta, ANTES de abrir el PR
kb hoja --cuerpo   # el texto que va a leer el revisor, uno por repositorio

kb hoja --cuerpo muestra lo mismo que kb pr manda: si la descripción salió de una plantilla del equipo, esa descripción con los bloques de kbspec al día; si no, el cuerpo estándar con el anexo.

Desde 3.178.1

Antes iba una tabla por componente, cada una con el título, los enlaces y las capturas repetidos: un repositorio con dos componentes daba un PR con todo dos veces. Medido sobre un PR real, el cuerpo bajó de 3.919 a 3.090 caracteres y ganó lugar para decir qué cambia.

Tres niveles de enlace

El revisor tiene el veredicto en la tabla sin un clic, cada evidencia a un clic —la celda enlaza directo al archivo en la vista de repos, porque el wiki solo renderiza .md y la evidencia de compilación es un .txt— y el contexto completo por los enlaces al wiki. Los enlaces apuntan a la rama donde kb publicar deja los archivos —la misma que usa el índice de cada carpeta—, así que andan también cuando la documentación vive en una rama propia y no en la principal del repositorio. Y el wiki es navegable de punta a punta: kb publicar siembra un índice autogenerado en cada carpeta sin página propia (entradas/, sp-db/, la que el requerimiento invente), porque Azure DevOps muestra en blanco una carpeta sin archivo propio.

Los enlaces al wiki

Debajo de los veredictos van enlaces a la evidencia completa —capturas incluidas— en el wiki de Azure DevOps donde está publicado el repositorio de documentación. El revisor la abre con un clic; nunca una ruta de disco.

kb wiki              # deduce organización, proyecto y wiki del remoto
kb wiki --escribir   # deja la URL en aplicaciones/TABLERO.md
kb wiki --publicar   # publica el repositorio como wiki, si aún no lo está

El wiki se crea una vez con «Publish code as wiki» sobre el repositorio de documentación — suele vivir en otro proyecto que el código, por eso la URL se declara y no se adivina. Dos detalles que muerden:

• El wiki publica de una rama: lo que se commitea en otra no aparece, y el enlace daría 404. kb wiki avisa cuando no coinciden.
• Quien revisa un PR ya tiene acceso Basic —Stakeholder no puede ver código en un proyecto privado—, así que no hace falta ninguna licencia adicional para leer el wiki.

El PR no nace antes que la documentación

kb pr verifica que el expediente esté publicado: con archivos sin commitear o commits sin push, el PR de código no se crea — enlazaría páginas que el wiki no tiene — y el mensaje da el remedio exacto (kb publicar). La secuencia queda blindada: kb pruebas → kb publicar → kb pr. Ver cómo se publica la documentación.

Cada evidencia con su enlace, y las capturas incrustadas

La tabla de veredictos enlaza directo a cada archivo —un clic, la vista de archivos del repositorio de documentación, el mismo acceso Basic— y no a la carpeta de evidencias. En los componentes con pantalla —los de tipo Frontend o App en el inventario; sin tipo, los que exigen E04 o E05— el PR lista además las capturas por caso, agrupadas: las de las E2E (E04-cpNN-<paso>.png) y las que se tomaron a mano antes del PR (E05-pantalla-cpNN.png), y la pantalla funcionando (E05-pantalla-<sistema>.png). Al PR de un backend no le llegan las de la web, aunque exija E2E, y una captura con el sufijo de otro componente es de ese. Al crearlo, kb pr las sube como adjuntos del PR —lo mismo que hace el navegador al pegar una imagen— y reescribe la descripción con las imágenes incrustadas, que se ven sin permisos sobre el repositorio de documentación. El enlace al archivo queda igual, por si la imagen no carga.

Solo la evidencia que se exige

evidencias/ tiene que contener exactamente lo que exige cada componente —su ficha (fila evidencias) o la tabla por tipo de PULL-REQUEST.md— y nada más. kb pruebas corre solo los comandos cuya evidencia está exigida (lo declarado y no exigido no se corre ni deja archivo; --todo lo corre igual), y lo exigido sin comando en la ficha se dice con la fila que falta: no se improvisa. La evidencia automática (E01–E04, E06, E10) la escribe kb con su cabecera; lo manual (E05 pantalla, E07 validador) se adjunta tal cual lo produjo una persona. Lo demás —resúmenes redactados, copias -final, salidas en UTF-16 redirigidas a mano, scripts— no cuenta: kb hoja y kb pr lo listan con su motivo y no lo enlazan. Los scripts de respaldo de kbspec viven en respaldo/, no entre las evidencias.

La plantilla del PR la define el equipo

En aplicaciones/pull-requests/*.md el equipo escribe qué lleva cada tipo de PR y en qué orden: una plantilla por destino (Release/*, develop, main, o el rol integracion / base), y si hace falta por aplicación o por equipo — la más específica gana. Cada plantilla mezcla dos cosas: {{evidencias}}, {{capturas}}, {{tareas}}, {{enlaces}}, ramas y work item, que kb llena solo y refresca en cada kb pr; y <!-- IA: instrucción -->, lo que redacta el agente siguiendo esa instrucción.

kb pr plantilla --escribir   # la plantilla resuelta, en evidencias/PR-descripcion-<sistema>.md
# … el agente redacta las secciones marcadas <!-- IA: … --> …
kb pr                        # refresca los bloques de kb; se niega si queda una sin resolver
kb pr --hacia main           # el PR de otro salto de la cadena, con SU plantilla

kb init-docs siembra dos (trabajo-a-integracion, integracion-a-base) y un LEEME que explica el formato. Sin plantillas, kb pr arma el cuerpo estándar de siempre y lo que redacta el agente va de anexo.

El anexo y el tope

Lo que redacta el agente vive en evidencias/PR-descripcion-<sistema>.md. Su primer párrafo es «qué cambia» y sube arriba de todo; el resto —el detalle técnico desde la bitácora y los ADR, cómo probarlo— va después de los veredictos (o en las secciones de la plantilla del equipo). El anexo no repite la hoja: si trae el título del PR, la tabla de evidencia o los enlaces, kb pr se niega a armar el borrador — pegar la salida de kb hoja --cuerpo ahí daba un PR con todo tres veces. Azure DevOps rechaza la descripción que pase de 4.000 caracteres UTF-16: si el cuerpo se pasa, se recorta el texto del agente — nunca los veredictos, los enlaces ni las capturas, que son lo que el revisor necesita para llegar al detalle.