OrenSegal/audit

Ejecuta una auditoría adversarial de este código fuente y complétala. Reporta y entrega primero; cambia el código fuente solo con --fix o una vez que el usuario elija correcciones.

Eres el adversario. Cada lente hace una pregunta desde un ángulo diferente: qué entrada, sincronización, usuario o atacante hace que este código dé una respuesta incorrecta, pierda datos, filtre datos o deje al usuario varado.

Esta carpeta contiene todo lo que la auditoría necesita. Resuelve estas rutas desde el directorio de este archivo:

• lenses/<lente>.md: uno por lente. Su línea Fires: indica cuándo se ejecuta la lente (always o when <condición>). Cada sonda es incondicional (siempre respondida) o está marcada (when <condición>) (se responde cuando la condición se cumple; de lo contrario, se cierra como no aplicable). Luego el artefacto que produce la lente y su línea de finalización.
• scripts/scan.py: toma las huellas del repositorio, enruta las lentes y lista los analizadores propios del proyecto para ejecutar. scripts/signals.tsv: cada patrón de detección y semilla; scripts/tools.tsv: cada analizador que conoce. Un proyecto agrega sus propias filas en docs/agents/audit-signals.tsv.
• scripts/verify.py: verifica los archivos de hallazgos contra los archivos de lentes. scripts/cochange.sh: archivos que cambian juntos.
• DELIVER.md: notas de entrega, el mapa de auditoría y sus tickets.
• UNTANGLE.md: la refactorización estructural, para --untangle y para tickets estructurales.

1. Alcance

• Argumentos: una ruta (por defecto: raíz del repositorio); --lens a,b para ejecutar solo esas; --since REF para auditar lo que cambió desde una referencia (una base de PR, o el commit de la última auditoría); --fix; --untangle [area|ticket] para saltar directamente a UNTANGLE.md; --out DIR (por defecto .audit/).
• Cuando no se pueda obtener respuesta (CI, claude -p), las preguntas sin respuesta permanecen en HANDOFF.md como preguntas abiertas, la entrega va solo al rastreador local y el código fuente no se modifica a menos que un ticket esté en la línea approved:.
• Crea el directorio de salida con un .gitignore que contenga *, para que la auditoría no toque ningún archivo rastreado. Al iniciar una nueva ejecución (nunca al reanudar), primero mueve la ejecución anterior de RUN.md, REPORT.md y findings/ a <out>/history/<su fecha>/, para que la nueva ejecución pueda comparar contra ella.
• Reanudar: si <out>/HANDOFF.md existe, continúa desde su fase next, dejando los archivos de la ejecución donde están. Los tickets en su línea approved: están autorizados para cambios de código sin preguntar de nuevo; trabaja el primero en la frontera, un ticket por sesión, como dice DELIVER.md. Cualquier otro ticket vuelve primero al usuario. Si existe una ejecución anterior en history/, ofrece --since <su commit> y traslada refuted.md hacia adelante.

Cada fase a continuación termina reescribiendo <out>/HANDOFF.md como describe DELIVER.md.

2. Escaneo y reconocimiento

Ejecuta python3 scripts/scan.py <path> [--since REF] [--lens a,b] > <out>/SCAN.md, de modo que SCAN.md sea la salida sin procesar del script: stacks, paquetes, qué lentes se disparan y por qué, puntos calientes, el plan de ejecución, los analizadores a ejecutar, sitios candidatos por sonda (archivos más calientes primero) y recuentos de casos especiales.

Ejecuta cada analizador listado en Herramientas cuyo comando esté disponible, guardando su salida en <out>/tools/<tool>.txt. Sus advertencias son pistas para la lente que nombra cada fila, al igual que los sitios de escaneo; una herramienta que falte o falle se anota en RECON.md y nunca se instala.

Luego escribe <out>/RECON.md, completando lo que un script no puede ver. Termina solo cuando cada encabezado tiene una respuesta o ninguno:

• Límites: todo lugar donde entran datos externos (HTTP, webhooks, lecturas de DB, archivos, entorno, enlaces profundos, cargas push, salida del modelo, entrada del usuario).
• Persistencia: almacenes locales, servidores DB, cachés, colas, y cuál posee cada hecho.
• Rutas críticas: dinero, autenticación, eliminación de datos, migraciones, cualquier cosa relacionada con seguridad, el bucle principal del usuario.
• Comandos: construir, probar, lint, ejecutar; si las pruebas pasan ahora.
• Reglas de la casa: CLAUDE.md/AGENTS.md; el lenguaje de dominio en GLOSSARY.md (o GLOSSARY-MAP.md), utilizado para cada nombre en hallazgos y correcciones; ADRs, cuyos riesgos aceptados permanecen firmes a menos que el riesgo haya cambiado; el rastreador de incidencias en docs/agents/.
• Condiciones: para cada lente que se dispara, qué sondas condicionales se cumplen aquí, con evidencia.
• Anulaciones de lentes: una lente que el escaneo omitió pero que el reconocimiento muestra que es necesaria, o una disparada por una señal falsa, con el motivo.

Escribe <out>/RUN.md: commit, fecha, argumentos, lista final de lentes.

3. Caza

Sigue el plan del escaneo: secuencial ejecuta cada lente aquí, una tras otra; paralelo asigna a cada lente un subagente, y una lente fragmentada un subagente por paquete listado. Un anfitrión que limita la concurrencia ejecuta oleadas, emparejando las lentes con la menor cantidad de sitios; un anfitrión sin subagentes ejecuta todo en secuencia.

Los subagentes comienzan sin habilidades y sin nada de esta conversación, por lo que cada instrucción se mantiene sola. Nombra: el archivo de la lente, este archivo (para Métodos y Formato de hallazgo), RECON.md, la sección de la lente de SCAN.md, el alcance y la ruta de salida <out>/findings/<lente>[-<paquete>].md. Los cazadores son hojas de solo lectura: leen código, ejecutan pruebas, scripts y la aplicación, escriben solo su archivo de hallazgos y reproducciones, y regresan al contexto principal, que solo despacha.

Métodos

• Autopsia anticipada: tres meses después del lanzamiento, la reseña de 1 estrella principal trata sobre esta área. Escríbela, luego encuentra el código que la causó.
• Inversión: ¿cómo harías que esta característica fallara lo peor posible? Verifica los bloques de código de cada manera.
• Registro de suposiciones: para cada función en una ruta crítica, enumera lo que supone. ¿Cuáles aplica un tipo o restricción, y cuáles dependen de la esperanza?
• Valla de Chesterton: antes de llamar a una guarda, caso especial o línea extraña un error, descubre por qué existe (git log -L, blame, el PR). Una valla con una razón viva no es un hallazgo.
• Los candidatos son pistas: un sitio de escaneo es un lugar para empezar a leer. Una sonda con cero sitios aún se responde, y un sitio se convierte en hallazgo solo con un escenario concreto.

Formato de hallazgo

### <LENTE>-<n> <la afirmación en menos de 60 caracteres>
- where: ruta:línea
- probe: <id de sonda del archivo de lente>
- scenario: <entrada, estado o sincronización concretos> → <resultado incorrecto que un usuario o sistema ve>
- severity: critical | high | medium | low
- detectability: loud (crash, alerta, test falla) | quiet (respuesta incorrecta que alguien puede notar) | silent (nadie notará)
- verdict: CONFIRMED (<la prueba, script, consulta o captura de pantalla que lo reprodujo>) | PLAUSIBLE (razonado, no ejecutado)
- fix family: <el tipo de cambio, no el parche>

Gravedad (severity): critical pierde o corrompe datos, infringe seguridad o privacidad, se equivoca en el dinero o arriesga la seguridad; high muestra una respuesta incorrecta o deja al usuario varado en una ruta común; medium hace lo mismo en una ruta rara o degrada la calidad; low es higiene. La gravedad se establece por quién puede desencadenarlo hoy en la configuración enviada: un escenario critical o high nombra a esa persona (cualquier visitante, cualquier usuario autenticado, un atacante que tenga X); una ruta que solo un operador o una configuración inactiva alcanza baja un nivel.

Redactar: los hallazgos, reproducciones, informes y tickets se compartirán. Escribe <REDACTED> en lugar de cualquier secreto, token o dato personal, y señala dónde vive en lugar de citarlo.

Un archivo de hallazgos se abre con el artefacto de la lente. Cada sonda termina en al menos un hallazgo o una línea clean:: clean: <sonda> — <evidencia>, o para una sonda condicional cuya condición no se cumple, clean: <sonda> — n/a: <por qué>. Un cazador termina cuando se cumple su línea de finalización y python3 scripts/verify.py <out> --root <path> --lens <lente> pasa.

4. Verificar

1. Fusionar duplicados entre lentes: cuando dos hallazgos comparten ubicación y mecanismo, conserva el bloque más grave, agrega - also: <los otros ids> y elimina el otro bloque, de modo que cada problema aparezca una vez.
2. Refutar: cada hallazgo critical o high recibe un refutador nuevo; el resto se agrupa por lente. Un refutador recibe solo el bloque del hallazgo, nunca el razonamiento del cazador. Para un hallazgo PLAUSIBLE, intenta matar la afirmación: una guarda aguas arriba, una restricción en la DB, una ruta inalcanzable, una valla con una razón. Para un hallazgo CONFIRMED, verifica la reproducción: ¿se pone rojo por la razón indicada, a través de código que un usuario o atacante real alcanza? Cuando el anfitrión ofrece un modelo diferente, los refutadores lo usan, ya que los sesgos compartidos hacen que el acuerdo del mismo modelo sea una evidencia débil.
3. Promover por evidencia: sobrevivido y reproducido → CONFIRMED; sobrevivido por razonamiento → PLAUSIBLE; matado → <out>/refuted.md con el motivo.
4. Crítico de cobertura: un subagente nuevo recibe las rutas críticas de RECON.md y todas las líneas clean: de cada lente, y nombra cada ruta crítica cuya evidencia sea débil (una oración donde se necesitaba un rastro o una prueba) o que ninguna lente haya alcanzado. Cada una vuelve a la lente correspondiente para una segunda revisión antes del informe.

Una reproducción es un bucle de retroalimentación ajustado que se pone rojo solo con este hallazgo y ningún otro: una prueba fallida en la costura más cercana, un script, una consulta. Construye una donde cueste menos de diez minutos, en <out>/repro/, solo contra sistemas locales, rama, entorno aislado o en modo de prueba. Un hallazgo matado por una razón que seguirá siendo válida el próximo trimestre (un riesgo aceptado, un compromiso deliberado) pertenece a un ADR, ofrecido en la entrega, para que las auditorías posteriores lo lean en el reconocimiento.

5. Informe

Escribe <out>/REPORT.md:

1. Resumen: recuentos por gravedad y lente, y las tres correcciones para hacer primero, con el motivo.
2. Correcciones: agrupa los hallazgos por causa raíz, cada corrección escrita encima de los hallazgos que soluciona; busca la única corrección detrás de varios hallazgos, que a menudo no se parece a ellos. Etiqueta cada uno como structural (acoplamiento, duplicación, un tipo faltante, un módulo superficial, una costura mal colocada) o local (un lugar, un cambio), y describe las correcciones estructurales en el vocabulario de módulo profundo: módulo, interfaz, profundidad, costura, adaptador, apalancamiento, localidad, la prueba de eliminación.
3. Hallazgos no agrupados, ordenados por gravedad, luego detectabilidad (silencioso primero), luego alcance.
4. Cobertura: todas las líneas clean: de cada lente, lentes omitidas con sus razones, analizadores ejecutados o faltantes, y lo que devolvió el crítico de cobertura.
5. Desde la última auditoría, cuando history/ contiene una ejecución anterior: corregidos, aún abiertos, nuevos y regresiones (corregidos antes, de vuelta ahora).

- Haz que el servidor sea el único escritor de `scan_count`, decrementado atómicamente con `where scan_count > 0`, para que el cliente no pueda desviarse, gastar dos veces o restablecerlo. [structural, critical]
  - MONEY-2 `ScanQuota.swift:40` decrementa localmente antes de la subida, y de nuevo al reintentar.
  - MONEY-3 reinstalar la app restablece `scansUsed` en el almacenamiento local a 0.
  - STATE-5 el cupo semanal se restablece el lunes local del dispositivo, por lo que volar hacia el oeste otorga una segunda semana.

Ejecuta python3 scripts/verify.py <out> --root <path>; el informe es definitivo cuando pasa. Cuando el anfitrión renderiza hallazgos estructurados (una herramienta ReportFindings), también reporta cada hallazgo sobreviviente allí, del más grave al menos.

Ajusta el embudo para este proyecto: una fila de semilla cuyos sitios terminaron todos refutados o limpios, o un hallazgo al que ninguna semilla apuntó, es una fila propuesta para docs/agents/audit-signals.tsv del proyecto. Enumera las propuestas en el informe; se escriben solo cuando el usuario las acepta.

6. Entregar y transferir

Lee DELIVER.md. Traza el informe como un mapa de auditoría con un ticket por corrección, con tipo, con bordes de bloqueo, en el rastreador de incidencias del repositorio (.scratch/ local cuando no haya ninguno configurado; confirma antes de publicar en un rastreador remoto). Luego pregunta qué correcciones comenzar como una ronda de sondeo: numera cada una como una pregunta con tu respuesta recomendada, redactada para que "sí" la acepte. Con --fix, toma todas las recomendaciones. Registra los números de ticket aprobados en la línea approved: de HANDOFF.md.

Enruta cada ticket según su forma. Las habilidades nombradas son mattpocock-skills; invoca una con la herramienta Skill cuando esté disponible, y de lo contrario realiza su paso directamente:

Forma del ticket	Ruta
Necesita una decisión primero: dónde va una costura, un ADR que contradice, un término de dominio difuso, un riesgo a aceptar	grill-with-docs, que registra la respuesta como un ADR y términos del glosario
Estructural, un módulo, vale la pena explorarlo con el usuario antes de comprometerse	improve-codebase-architecture en esa área
Estructural, diseños de interfaz en competencia	codebase-design, su patrón diseño-dos-veces
Estructural, el camino está claro y cabe en una sesión	UNTANGLE.md, con el ticket y REPORT.md como su lista inicial
Estructural, más grande que una sesión	wayfinder, trazando tickets de decisión hacia el destino
Muchas correcciones para dividir para agentes que trabajan sin supervisión	to-tickets (rebanadas trazador, bordes de bloqueo, refactorizaciones amplias como expandir–contraer), luego implement
Corrección local	tdd: la reproducción es la primera prueba roja, en una costura acordada con el usuario; la suite completa permanece verde
PLAUSIBLE y critical, sin reproducción aún	diagnosing-bugs fase 1: construye el bucle ajustado primero

Cuando la frontera esté vacía, vuelve a auditar con --since <el commit de auditoría>. El destino de la auditoría es una re-auditoría que verifica que no haya hallazgos critical o high sobrevivientes.

Terminado cuando

• Cada lente que se dispara tiene un archivo de hallazgos que cumple su línea de finalización, y verify.py pasa en toda la salida.
• Cada hallazgo sobreviviente tiene ubicación, sonda, escenario, gravedad, detectabilidad y veredicto; todo hallazgo matado está en refuted.md.
• REPORT.md coloca cada hallazgo bajo una corrección o en la lista no agrupada, el mapa tiene un ticket por corrección, y HANDOFF.md nombra el siguiente ticket.