El rastro que responde a una auditoría

Un supervisor no pregunta si el código compila. Pregunta quién pidió el cambio, qué IA lo escribió, con qué criterio se aprobó y quién lo revisó, y lo pregunta meses después, sobre todos los requerimientos a la vez. kbspec contesta desde un registro que se escribe solo mientras se trabaja, no desde la memoria de nadie.

La cadena: `auditoria.jsonl`

Cada expediente lleva su rastro. La CLI anota sola cada comando que cambia algo o que es una compuerta —init, ramas, publicar, validar, uat…— con la hora, quién lo corrió y con qué resultado. Los de solo lectura no entran: kb estado se corre cincuenta veces por día. Lo que el panel o el servidor MCP corren para leer tampoco; lo que corren para cambiar algo, sí, marcado desde: panel.

Solo se agrega. Cada evento lleva el hash SHA-256 del anterior y el suyo: editar una aprobación o borrar un evento del medio rompe la cadena.
No guarda contenido. Nombres de comando, rutas, conteos y resúmenes de una línea. Los argumentos pasan por lista blanca, para que un --token que alguien agregue mañana no se cuele.
Romperla cuesta algo. kb validar cuenta la bitácora alterada como brecha: el expediente no pasa la compuerta del Pull Request y el check kbspec/expediente del PR de código sale en rojo.

Anclas fuera del archivo

La cadena sola es SHA-256 sin clave: quien puede escribir el archivo puede truncarlo o recalcularlo entero. Por eso kb publicar deja la cabeza del rastro como etiqueta git anotada kbspec-rastro/<TICKET>/<seq> en el repositorio de documentación y la sube al remoto; git fetch --tags trae las del resto del equipo. Un evento anclado que falta o que cambió se denuncia, un génesis a mitad del rastro no se acepta, y un expediente con anclas y sin auditoria.jsonl es un error, no «nada que verificar».

`kb auditoria`

kb auditoria                     # qué se corrió, quién, cuándo y con qué resultado
kb auditoria --verificar         # la cadena entera, contra sus anclas
kb auditoria --verificar --base origin/Release/PN-00142
kb auditoria --certificar        # todos los expedientes del repositorio
kb auditoria --dossier           # el expediente de cumplimiento

--base <ref> compara además contra el rastro de la rama destino del PR. El archivo solo crece: un evento de allá que falta acá es un borrado o una reescritura.
--certificar emite un certificado con fecha, emisor, período cubierto y cantidad de eventos, y separa tres cosas: íntegros, alterados (con el evento y el motivo) y sin bitácora, porque «nada que verificar» no es «verificado». Sale con 1 si algo está alterado, así que sirve en un pipeline; --json para herramientas.
--anotar fase|decision|aprobacion|excepcion --resumen "…" registra lo que la CLI no ve: una aprobación dada en una reunión, una regla que se saltó y por qué. Lo corre una persona.

El punto de control

kb validar corre en cada refresco del panel, y volver a hashear 50.000 eventos costaba más de un segundo. Desde 3.178.0 verifica desde un punto de control: lo ya verificado no se vuelve a hashear, pero el punto de control guarda la huella exacta de esa parte del archivo, así que un solo byte cambiado obliga a verificar todo. Vive en el .git del repositorio de documentación: es local y no viaja. kb auditoria --verificar y la CI verifican siempre la cadena entera.

Lo que contesta el dossier

kb auditoria --dossier arma evidencias/dossier-auditoria.html: autocontenido, sin red y sin scripts, pensado para imprimirse o para abrirse dentro de diez años. Sigue el orden en que se pregunta:

Sección	De dónde sale
Qué cambio es · quién lo pidió	El frontmatter; quién abrió el expediente y cuándo, el solicitante declarado y dónde está la solicitud literal (`01`)
Qué IA generó cada fase	El modelo que se resolvió de la traza del asistente al cerrar cada fase, no uno declarado a mano
Con qué criterio se aprobó	El último veredicto de `kb spec`, `kb listo`, `kb validar` y `kb pruebas revisar`, las aprobaciones con la identidad de quien firmó —verificada por el servidor o declarada—, la separación de funciones y los pasos propios del ciclo
Quién lo revisó	El estado del PR, la ronda y las tareas que el desarrollador validó y cerró
Evidencia · trazabilidad	`evidencias/` y las brechas de la cadena `RF → tarea → caso → evidencia`
Integridad · política de IA	La verificación de la cadena y sus anclas; `aplicaciones/IA.md` tal como regía
Línea de tiempo	Todos los eventos, con los ajenos marcados

Lo que no está, lo dice. Un expediente anterior a 3.144.0 sale sin modelo ni veredictos, y así se entrega: un dossier que rellena huecos se ve igual que uno completo. Los eventos de otra carpeta no se borran, se declaran (ver El expediente). El formato de la casa va en aplicaciones/plantillas/dossier-auditoria.md, pero una plantilla no relaja un control: lo que no muestra va igual, como anexo.

Lo que kbspec hizo en el tablero

Cada sincronización con el tablero deja un evento —no uno por tarea— con los work items creados, los cambios de estado y el wid anotado; la que falla queda con su motivo. El dossier lo resume en «En el tablero»: el plan dice qué tareas hay, y esto dice qué se creó y qué se movió.

El rastro en el SIEM

Seguridad no lee un auditoria.jsonl dentro de un repositorio: lee su SIEM. kb auditoria --exportar le lleva el rastro un evento por línea, con lo que necesita para correlacionar —expediente, ticket, seq, fecha, evento, resultado, actor, versión— y para verificar: cada evento viaja con su hash y su prev, así que la cadena se comprueba del otro lado.

kb auditoria --exportar                                   # lo nuevo del expediente (jsonl)
kb auditoria --exportar --todos --formato cadf --salida /ruta/kbspec-auditoria.jsonl
kb integracion siem --url https://splunk.banco.local:8088 --tipo splunk
kb auditoria --exportar --todos --enviar                  # con KB_SIEM_TOKEN en el entorno

Solo lo nuevo, por destino. Cada máquina recuerda qué recibió cada destino, por hash: el evento de otra máquina puede llegar con un seq menor al último que salió. --desde-cero repite todo.
Un archivo para el agente del SIEM, el camino habitual en un banco: --salida agrega, y las plantillas de pipeline traen el paso, comentado.
O directo a Splunk HEC o a un webhook HTTPS. El destino lo declara cada máquina y el token vive solo en KB_SIEM_TOKEN: no se guarda, no se imprime y no va en la URL. Sin https no sale, salvo a la propia máquina, y una redirección no se sigue.
Nada se pierde: lo exportado se anota cuando llega. Con un SIEM declarado, kb publicar manda lo nuevo y, si no puede, lo dice sin frenar; KB_SIN_RED apaga ese envío automático, no el que se pide con --enviar.

CADF	De dónde sale
`id`	UUID v5 del hash del evento: una reexportación se deduplica
`eventType` · `eventTime`	`activity` · la fecha del evento
`action`	verbo CADF calificado: `create/kb-init`, `evaluate/compuerta`, `allow/aprobacion`, `update/<evento>`
`outcome`	`success` si el resultado es `ok`; si no, `failure`
`initiator` · `target` · `observer`	quien lo hizo (si fue una IA, el modelo) · el ticket y su carpeta · `kbspec`
`attachments`	el evento original entero, con `hash` y `prev`

Lo que decide una persona

Once comandos son decisiones humanas, y el rastro los lee así: kb ciclo aprobar, kb pr aprobado, kb tarea --todas, kb tarea T-NN sin --hecho (el cierre sin la compuerta), kb configuracion verificar, kb finalizar, kb auditoria --anotar, kb lote autorizar, kb presupuesto autorizar y kb insumo --sin-guarda y kb pr --aplicar --si (crear el PR sin la casilla del borrador). La compuerta se los niega al agente en cualquier forma —kb, kb.cmd, python …/kb.py, npx kb, encadenados con &&—, deja el intento en el rastro y le dice que se lo pida al desarrollador. En la terminal del agente nunca se aprueban solos, y KB_SIN_COMPUERTA no los destraba: el agente nunca necesita aprobar.

La aprobación del PR se lee del servidor. kb pr aprobado mira los votos —en Azure DevOps, 10 o 5 aprueban y -10 rechaza; en GitHub, la última revisión de cada persona—. Sin un aprobado, o con un rechazo, no se sella. --forzar la deja como declarada, y el dossier distingue «verificada — votos de …» de «declarada».
Cada evidencia que escribe kbspec deja su huella SHA-256 en el rastro. En un expediente que ya sella, un archivo sin huella —inventado o retocado— no cuenta y el PR no lo enlaza.
El commit dice de dónde viene. El de cada tarea lleva trailers de git: Kbspec-Expediente, Kbspec-Tarea, Kbspec-Modelo (el de la traza, no el que dice el agente), Kbspec-Rastro y Kbspec-Version. Desde el historial del código se vuelve al expediente.

Firmado con la identidad que dice el servidor

Aprobar un paso del ciclo, autorizar un lote o un presupuesto, confirmar la configuración, dar por terminado el requerimiento o firmar el borrador del Pull Request queda a nombre de quien dice Azure DevOps (o GitHub) que es el dueño de la credencial con la que trabaja esa máquina, además del correo que la máquina declara. Si no se pudo verificar —sin credencial, sin red— queda escrito por qué. Ni una variable de entorno, ni un archivo, ni un servidor en la propia máquina pueden fabricar esa identidad.

Lo que escribe un subagente no es de la persona

La aprobación escrita en el chat («aprobado 02») la lee el gancho del mensaje. El motor de Copilot le pasa a ese mismo gancho el pedido que el agente le escribe a un subagente, con el mismo formato que un mensaje de la persona. Por eso la compuerta niega el pedido a otro agente que empieza con una decisión, y una decisión que llega de una sesión que kbspec no vio arrancar —un subagente nunca dispara el arranque de sesión— se registra marcada: «⚠ desde una sesión que kbspec no vio arrancar», en kb auditoria, kb diagnostico y el dossier, para que alguien revise la conversación antes de darla por buena.

Quien aprueba no es quien escribió el código

Cuando la aprobación da por bueno el código —un paso del ciclo desde la implementación, el cierre del requerimiento, los votos del Pull Request—, kbspec compara a quien aprueba con los autores de los commits de la rama de trabajo. Al crear el PR anota quién la escribió: después de integrada, es lo que se sigue comparando.

Ajuste de `aplicaciones/IA.md`	De fábrica	Estricto
`identidad_en_aprobaciones`	`registrar`: anota lo que haya	`exigir`: sin identidad verificada no se firma
`separacion_de_funciones`	`avisar`: lo dice y queda en el rastro	`exigir`: el autor no firma (y `apagado` no mira)

Endurecerlos rige al instante; aflojarlos, solo cuando el cambio llega a la rama principal por Pull Request. El dossier muestra, por cada decisión, si la identidad fue verificada o declarada, si aprobó quien escribió el código y qué firmas negó la política. kb check --seguridad dice con qué identidad firma una máquina antes de que haga falta.

Apagar las compuertas con KB_SIN_COMPUERTA=1 sigue siendo posible, pero deja el evento compuerta apagada una vez por día, y el dossier dice cuántos días se trabajó así.

La validación del usuario cuenta si dice quién

La plantilla del 07 anterior a 3.178.0 traía | CP-01 | ✅ | de ejemplo, y en los expedientes creados con ella CP-01 figuraba aprobado por el usuario sin que nadie lo ejecutara. Desde 3.178.1, si la validación del usuario trae la línea «Ejecutada por» vacía o con el marcador, sus vistos buenos no cuentan: un ✅ sin quién lo dio no vale ni para la compuerta de los P0 ni para la trazabilidad. Un ❌ o un ❓ sin nombre, en cambio, siguen contando: son un defecto o una duda que alguien vio, y descartarlos daría por aprobado lo que el usuario reprobó. kb uat importar la completa con lo que devuelve el usuario, y kb validar dice qué restos de la plantilla quedan por borrar: resultados sin quién, hallazgos de ejemplo —que ya no cuentan como defectos abiertos en las métricas— y la §2 de antes.

Quién es quién, cuando no hay servidor. Desde 3.179.0 cada decisión anota la identidad que dice el tablero; sin credencial o sin red queda declarada —el correo de git config user.email, y --por/--quien el nombre que se escribió— y el dossier lo dice. Con identidad_en_aprobaciones: exigir, una firma sin identidad verificada no se registra. La separación de funciones compara correos y cuentas: un autor que commitea con otro correo que el de su cuenta no se reconoce.
Lo que no se publicó. Las anclas cubren hasta el último kb publicar que llegó al remoto; lo posterior descansa solo en la cadena. Si el push de la etiqueta falla, el ancla queda en esa copia hasta el próximo kb publicar, y lo dice.
Lo anterior a cada control. Sin modelo ni veredictos antes de 3.144.0; sin anclas ni huellas de evidencia antes de 3.175.0. El dossier lo dice en vez de rellenarlo.