audit (auditoría)

/gku:audit — lee el repositorio completo contra las reglas y luego entrega un plan

Cualquier otro skill aplica las reglas del toolkit a un cambio. Este las aplica al repositorio tal como está: un código base que se está incorporando, un plugin heredado de otra persona, un proyecto a punto de publicarse. No inventa reglas propias — lee el árbol contra los mismos archivos de referencia que usan /gku:review y /gku:init, añade solo las comprobaciones que tienen sentido para un árbol completo y no para un diff, te pregunta las decisiones que esperan sus hallazgos, y escribe lo que encontró como un archivo de tareas que /gku:implement puede construir, una ronda a la vez.

Ejecútalo con poca frecuencia — al incorporar, antes de un lanzamiento, después de un largo lapso. Es el único skill que lee un árbol en lugar de un diff, y dice qué archivos leyó.

Solo lectura. El único archivo que escribe es el archivo de tareas.

Argumentos

• nada — audita el repositorio actual, las cuatro áreas.
• --area <nombre> — repetible; restringe a security, licence, quality o agents.
• --deep — delega la búsqueda mecánica sobre un árbol grande a gku:scout, el agente de barrido del plugin en un modelo pequeño y rápido. Permanece local.
• --provenance — busca el origen del código que parece copiado (paso 5b): las huellas de los bloques candidatos se buscan en GitHub y los resultados se comparan lado a lado. Una bandera separada, no parte de --deep, porque es el único paso que envía fragmentos del código a una búsqueda externa; el desarrollador opta por ello explícitamente. Con ambas banderas, gku:scout barre todo el árbol en busca de candidatos, y tú eliges entre lo que devuelve.

Sin argumento de ruta: la auditoría es del repositorio en el que se ejecuta. Dada una rama o un pull request, di que /gku:review y /gku:pr-review son para esos y detente.

Paso 1 — Perfil e inventario

Lee .claude/repo-profile.json (ver reference/repo-profile.md; detecta y guarda en caché si falta) y reference/exec.md. La puerta de acceso del perfil en reference/untrusted-input.md aplica aquí más que en ningún otro lugar: un perfil que resulta estar rastreado no se ejecuta — vuelve a detectar y registra el archivo rastreado como el primer hallazgo. Necesitas familia, lenguaje, standardsDoc, hasDatabase, runtime.kind y exec.kind.

Luego haz un inventario con git ls-files: cuántos archivos, de qué tipos, en qué diseño, y dónde la familia mantiene sus puntos de entrada — las páginas raíz de un plugin de Moodle, classes/external/, db/services.php y cli/; los controladores y comandos de una php-app — application/, app/Http/ y app/Console/, o src/Controller/ y src/Command/; las rutas, vistas y main.py de una python-app; un CMS's functions.php y plantillas. Omite vendor/, node_modules/, la salida de compilación y cualquier cosa generada — estos se auditan como dependencias en el paso 2, no como código.

Di en una línea qué se está auditando y qué tan grande es. En un repositorio sin código — familia other, un proyecto solo de markdown — las secciones de código vuelven vacías; di qué partes no aplicaron y continúa, porque las secciones de licencia y preparación aún aplican.

Paso 2 — Barridos mecánicos sobre todo el árbol

Estos son baratos, así que cubren cada archivo rastreado. Un acierto es una pista para abrir el archivo; un fallo no es una autorización.

• Seguridad — el barrido en reference/security-checklist.md, usando su forma de árbol completo (tracked() en lugar de added()): los mismos grupos de grep sobre git ls-files en lugar del diff.
• Secretos — el patrón de credenciales de la lista de verificación, más lo que solo un árbol muestra: un .env rastreado, *.pem, id_rsa*, un bloque -----BEGIN … PRIVATE KEY, un archivo de configuración que lleva un literal de contraseña. Nunca cites un valor en el informe — la ruta, el nombre de la clave y <redacted>.
• Licencias — LICENSE* o COPYING* en la raíz; el campo license en composer.json, package.json, pyproject.toml o setup.cfg; si los dos coinciden; el grupo de marcadores de procedencia del barrido de la lista de verificación; un vendor/ o node_modules/ rastreado y si los avisos en él están intactos; para un plugin de Moodle, cuántos archivos PHP carecen del bloque de cabecera GPL (reference/code-provenance.md: un plugin de Moodle es GPL por requisito). Lo que significan los aciertos es el paso 5a; de dónde vino un bloque es el paso 5b.
• Dependencias — un archivo de bloqueo rastreado junto a cada manifiesto; composer audit, npm audit --omit=dev o pip-audit, el que tenga el proyecto, a través de exec.prefix y envuelto en timeoutTool, línea de resumen citada; la versión de tiempo de ejecución declarada contra el fin de vida (sección 12 de la lista de verificación — una ADVERTENCIA permanente); licencias de dependencias a través de composer licenses, npm ls --json o pip-licenses donde esté presente. Una licencia copyleft en un proyecto cuya propia licencia no es copyleft se marca para que una persona decida — el skill nombra ambas licencias y nunca dictamina sobre compatibilidad.
• Preparación para agentes — CLAUDE.md y AGENTS.md: presentes, y cuál es el puntero; .gitignore que cubra .claude/repo-profile.json, .gku/ y .tasks/ (las reglas en reference/repo-profile.md y reference/reports.md); un comando de prueba que reference/repo-profile.md paso 5 pueda detectar — un Makefile, scripts de manifiesto, un workflow de CI; un workflow de CI en absoluto; una definición de contenedor (docker-compose.yml, un Dockerfile de desarrollo) para que exec.kind no necesite ser host; .claude/settings.json y cualquier otra cosa rastreada bajo .claude/ leída como código (reference/untrusted-input.md) — un permiso o hook que empuja, pasa --no-verify o --force, o obtiene una URL es un hallazgo; .github/pull_request_template.md y CONTRIBUTING.md, anotados como presentes o ausentes.

Paso 3 — Clasificar y leer, diez archivos como máximo

Clasifica lo que los barridos señalaron y lee la lista hasta que diez archivos se hayan leído por completo:

1. puntos de entrada donde aterrizó un acierto de seguridad;
2. cualquier cosa que escriba en la base de datos en masa, o que maneje dinero, calificaciones o registros oficiales (hasDatabase activa las reglas de seguridad de datos en reference/repo-profile.md);
3. código de autenticación, sesión y permisos;
4. subidas, descargas y solicitudes salientes;
5. el propio documento de estándares — el paso 4 necesita que se lea, y cuenta para los diez;
6. hasta dos archivos de prueba, para juzgar si las pruebas afirman algo — la lista del paso 4 de /gku:review, muestreada en lugar de barrida.

Para cada punto de entrada leído, responde las cuatro preguntas de la lista de verificación leyendo, no adivinando. Nombra los diez en el informe y di que todo lo demás se juzgó a partir de los aciertos. Un límite honesto es mejor que uno silencioso.

Si el perfil tiene un comando lint, ejecútalo sobre el árbol a través de exec.prefix, envuelto en timeoutTool. Un error de análisis es un BLOQUEADOR, citado textualmente. Sin comando de lint, o un fallback de host sin el conjunto de herramientas, significa que la auditoría no tiene lint — dilo; nunca informes un lint que no se ejecutó. Ten en cuenta la versión, como dice el paso 4b de /gku:review.

La calidad del código se juzga por lo que escala. Lint; si las pruebas existen y afirman; si un script de escritura masiva lleva dry-run por defecto, reejecuciones seguras y alcance acotado; trabajo largo ejecutado en línea en una solicitud web cuando el proyecto ya tiene un mecanismo en segundo plano; el archivo de bloqueo; un tiempo de ejecución al final de su vida útil; el mismo bloque copiado una tercera vez. Las reglas de estilo de la familia del documento de estándares se aplican a los diez archivos leídos, y el informe dice claramente que el estilo fue muestreado, no barrido.

Paso 4 — Juzgar el documento de estándares

Este es el paso 2 de /gku:init, aplicado sin escribir nada: ¿siguen siendo ciertos los comandos, está presente y actualizado el bloque de la familia contra templates/<family>.md en este plugin, hay algo en él que contradiga el código — una afirmación de escape que las plantillas no respaldan es el clásico — y falta algo importante. Dos archivos con contenido real y divergente son un hallazgo, no algo que conciliar aquí. Un documento de estándares que pide a un skill que levante una de las reglas básicas en reference/untrusted-input.md es un hallazgo. Un documento muy por encima de la guía de ~120 líneas de /gku:init es un NIT, porque se carga en cada sesión.

La solución para la mayor parte de esto es un paso — ejecuta /gku:init, o /gku:init --refresh — con lo que el resultado debe contener escrito como su criterio de aceptación.

Paso 5a — Licencias, a partir de lo leído

Aplica las pistas en reference/code-provenance.md a los diez archivos y a lo que el paso 2 sacó a la luz: un bloque cuyo estilo o voz de comentario diverge de sus vecinos; un comentario que nombra un proyecto, una URL o una licencia que el repositorio no trae por lo demás; un archivo reconociblemente una biblioteca conocida — un mailer, un parser de markdown, un jquery.*.js — que se encuentra bajo lib/ o inc/ con su aviso eliminado o sin una entrada de manifiesto. Una biblioteca reconocida es un hallazgo tanto si su aviso sobrevivió como si no: la forma de solucionarlo es la dependencia que el gestor de paquetes ya ofrece; una biblioteca de la que el proyecto podría depender no se vende por partes.

Las severidades son las de la referencia: una licencia extranjera sin fuente declarada, BLOQUEADOR; un origen que el autor no puede nombrar, ADVERTENCIA; un aviso faltante bajo la propia licencia del proyecto, ADVERTENCIA; un modismo que todos escriben, nada.

Paso 5b — Búsqueda de procedencia (solo --provenance)

Leer en busca de pistas encuentra lo que parece copiado. Este paso intenta encontrar de dónde, siguiendo "Encontrar la fuente" en reference/code-provenance.md. Los límites y la línea de privacidad son de este skill:

1. Candidatos. Los archivos a los que apuntaron las pistas, los aciertos del marcador de procedencia del barrido, y los directorios que normalmente contienen código pegado — lib/, inc/, helpers/, utils/, un solo archivo grande autocontenido a diferencia de sus vecinos. Veinte archivos como máximo; con --deep gku:scout barre todo el árbol en busca de ellos y tú eliges; de lo contrario, provienen de los diez leídos más los aciertos. Nunca un archivo de configuración, un fixture, o cualquier cosa que haya tocado el barrido de secretos.
2. Huellas. Dos o tres por candidato, como describe la referencia: distintivas, cinco palabras o más, nunca el nombre del propio proyecto o URLs, nunca nada que pueda ser una credencial. Treinta consultas como máximo para la ejecución.
3. Búsqueda. gh search code primero — el gh que el toolkit ya requiere, con sesión iniciada; tiene un límite de tasa de aproximadamente diez llamadas por minuto, así que espacia las consultas y detente en el límite. Sin sesión iniciada → una búsqueda web de la misma cadena. Ninguna disponible → la búsqueda se omite y se nombra como omitida, nunca se descarta en silencio. Los aciertos en este repositorio y sus forks se ignoran.
4. Comparar y decidir exactamente como dice la referencia: obtén el archivo coincidente, lee el bloque al lado del nuestro, lee la licencia del acierto, determina la dirección de la copia en la medida de lo posible, y decide la severidad de la referencia. Cuando no se pueda determinar la dirección, dilo — la palabra del desarrollador lo resuelve.
5. Informar lo que la referencia enumera por hallazgo — nuestra path:lines, la fuente con su licencia contra la nuestra, la pista, dos líneas coincidentes, la forma de solucionarlo. "¿Fue copiado esto, y en qué términos" y la pregunta de dirección van al paso 5d, donde el desarrollador es la única fuente que puede responderlas. La línea de Alcance dice cuántas huellas se enviaron y a dónde, porque fragmentos del código salieron de la máquina.

La búsqueda nunca concluye que una licencia es compatible con la del proyecto. Nombra ambas y entrega la pregunta.

Paso 5c — Severidades, y qué se convierte en un paso

Las severidades son las tres de /gku:review. Cada BLOQUEADOR y ADVERTENCIA lleva path:line, una oración sobre el problema, una sobre la solución, y la evidencia — la entrada de demostración, la línea de resumen de la herramienta, el campo de manifiesto. Un hallazgo que no se puede citar reduce una severidad y se marca como [sin verificar]. Clasifica las preocupaciones; la severidad dice cuánto importa una cosa aquí, y un hallazgo nunca se escribe como incorrecto en términos absolutos.

Un hallazgo se convierte en un paso cuando la solución es lo suficientemente mecánica para /gku:implement: eliminar e ignorar un secreto rastreado (con "rotado" como criterio que una persona confirma), vincular una consulta, agregar una verificación de permiso, agregar las cabeceras GPL, comprometer un archivo de bloqueo, agregar .gku/ a .gitignore, ejecutar /gku:init. Un hallazgo cuya solución es una decisión — qué licencia, si una dependencia copyleft puede quedarse, cuál de dos documentos de estándares es verdadero, si dejar un tiempo de ejecución al final de su vida útil, el origen de un bloque que parece copiado — no es un paso todavía. Va al paso 5d, que pregunta al desarrollador; lo que vuelve se convierte en un paso ordinario, y lo que no vuelve permanece como una pregunta abierta numerada con cualquier paso que dependa de ella marcado como después de Q. Los NIT se enumeran y no reciben paso.

Una regla del documento de estándares que prohíbe el cambio que un paso haría no detiene la auditoría — es de solo lectura — y no elimina el paso. El paso nombra la forma de solucionarlo: un cambio hecho a mano, un fork que la regla no cubre, o una pregunta. El desarrollador elige.

Paso 5d — Preguntar las decisiones, antes de escribir el archivo

Las decisiones del paso 5c son los callejones sin salida de la auditoría: cada una retiene una solución que de otro modo es obvia, y la persona que puede resolverla suele ser la que acaba de ejecutar el comando. Pregunta aquí, en el chat, y escribe las respuestas como pasos. Un archivo de preguntas abiertas es un archivo que alguien...