Escribir una política

Hay dos formas de escribir una política: dejar que Failproof AI la redacte a partir de un hallazgo de auditoría, o escribir el código tú mismo. Nada se publica ni se despliega hasta que tú lo decidas.

Escribir una política a partir de una auditoría

Una auditoría detecta un fallo; una política evita que vuelva a ocurrir. Failproof AI redacta la política a partir de la evidencia del propio hallazgo.

1. Ejecutar una auditoría

Ejecuta una auditoría sobre las sesiones donde ocurre el fallo. Cada hallazgo contiene sus sesiones de evidencia, una causa raíz y una ruta de prevención sugerida. Trabaja a partir de un hallazgo con un patrón de acción repetible — una política solo puede detener aquello que puede reconocer en un evento de hook.

2. Generar el borrador

Dashboard
CLI

Abre el issue del hallazgo en Analyze → issues y revisa las sesiones citadas, la causa raíz y la recomendación.
Selecciona generate policy. Failproof AI primero indica si una política puede expresar el problema en absoluto. Un resultado no policy significa que la solución es una alerta, un cambio de flujo de trabajo o una persona — no una política.
Selecciona write this policy. El título del issue, el hallazgo, la causa raíz, la recomendación y la intención de aplicación propuesta se convierten en un borrador en Admin → policy editor. Usa open the editor anyway cuando no estés de acuerdo con la verificación de candidatura.

Lee la evidencia y luego redacta con el asistente. compose imprime el código fuente para que lo revises y no publica nada:

fp issues show <issue-id>
fp audits finding <finding-id>
fp policies compose "Block git push --force on release branches"

compose requiere una sesión con sesión iniciada (fp login) cuyo rol tenga policies:write; rechaza las claves de API.

3. Revisar el borrador

Un borrador es un punto de partida, no un veredicto. Antes de publicar, verifica que:

Nombra el modo de fallo en lenguaje operativo.
Coincide solo con los eventos de hook y las herramientas que contienen suficiente evidencia para decidir.
Usa la condición más restrictiva posible que detecte la acción no segura.
Devuelve un motivo que indique al agente qué hacer en su lugar.
Usa instruct cuando el agente pueda corregir el curso de forma segura, y deny solo cuando permitir la acción sea inaceptable o irreversible.

Valida el código fuente en el editor y corrige cada error reportado.

4. Probarlo y luego publicarlo

Ejecuta backtest sobre el código fuente antes de publicar: repite el borrador contra las llamadas que tu flota ya realizó y cuenta las llamadas correctas que habría interrumpido. Probar una política cubre ese proceso y las demás comprobaciones. Cuando se comporte como se espera, introduce la identidad de la política y selecciona publish version. Publicar genera una versión inmutable y no despliega nada: permanece inactiva hasta que la despliegues. Desde un terminal:

fp policies publish checkout-guard ./checkout.policy.mjs --description "Block force-push"

publish verifica la sintaxis del código fuente antes de enviarlo, por lo que un error de sintaxis se detecta aquí en lugar de en una máquina durante la aplicación.

Escribirla tú mismo

Una política es JavaScript o TypeScript sobre la API de failproofai:

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "protect-production-paths",
  description: "Block writes to production configuration",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
    const path = String(ctx.toolInput?.file_path ?? "").replaceAll("\\", "/");
    if (path.split("/").includes("production")) {
      return deny("Writes to production configuration require approval.");
    }
    return allow();
  },
});

Esto coincide con production/config.yml, /srv/production/config.yml, /srv/production y C:\\production\\config.yml tanto para Write como para Edit, pero no con production-backup: production tiene que ser un segmento de ruta completo. El contexto también contiene el tipo de evento, el payload normalizado, los metadatos de sesión, los parámetros y la CLI de origen cuando están disponibles — consulta el SDK de políticas. Para publicarlo como una versión, pega el código fuente en compose en Admin → policy editor y sigue los pasos 3 y 4 anteriores, o publica el archivo desde un terminal con fp policies publish. Para ejecutarlo en una máquina sin Cloud, guárdalo en .failproofai/policies/ con un nombre que termine en policies.js, policies.mjs o policies.ts — estos se cargan automáticamente en el ámbito de proyecto y de usuario — o instálalo por ruta:

failproofai policies --install --custom ./security.policies.ts --scope project

Dale a cada política un nombre único entre las políticas de convención, personalizadas, de paquete y gestionadas por Cloud.

Prevent repeat failures

Get a policy

Ship a policy