Sentinel — guardrails de arquitectura en cada commit

Sentinel es un binario Go (korva-sentinel) que escanea archivos staged al momento del commit y bloquea el commit ante violaciones graves. Es la segunda mitad de Korva — Vault le da memoria a la IA, Sentinel se asegura de que no pueda mandar código malo aunque ignore esa memoria.

Tres formas de ejecutarlo

1. Hook pre-commit (recomendado). Instalado por korva sentinel install, corre automáticamente en cada git commit.
2. Escaneo manual. korva sentinel check ejecuta el validador sobre los archivos actualmente en stage e imprime los hallazgos sin commitear.
3. CI/CD. korva-sentinel --format json emite un reporte parseable que puedes publicar en PRs de GitHub o guardar como artefacto del build.

CLI

korva-sentinel [--format text|json] [--profile minimal|standard|strict] [--fail-on-warning] [files...]

Inputs:

• stdin: git diff --cached --name-only | korva-sentinel
• args explícitos: korva-sentinel src/domain/x.ts src/application/y.ts

Output:

• text — íconos coloreados (✓ pass, ✗ error, ⚠ warning) con archivo:línea:col
• json — reporte estructurado para tooling

Perfiles de severidad

Familias de reglas built-in

Reglas documentadas (cargadas por YAML)

Puedes dejar un archivo <rule-id>.yaml en .korva/rules/ y Sentinel lo recoge. Ver sentinel/rules/AGENTS.md para la referencia canónica. Highlights:

• ARC-001 — imports de frameworks (express, nestjs, prisma…) dentro de domain/core
• ARC-002 — funciones de más de 25 líneas o llamadas a DB dentro de handlers HTTP
• ARC-003 — db.query, prisma.*, mongoose.* fuera de repository/store
• SEC-002 — logger.info(password), console.log(token) con nombres de variable sensibles
• SEC-003 — igualdad directa (==/===) sobre valores de token/secret/HMAC/firma (timing attack)
• SEC-004 — CORS con origin: "*" o Access-Control-Allow-Origin: *
• SEC-005 — SQL en template literals con interpolación
• SEC-006 — rutas admin/internas/de usuario sin middleware de autenticación
• QC-001 — console.log, debugger;, breakpoint() en src/
• QC-002 — : any / as any sin justificación
• DEPS-001 — imports de paquetes vulnerables (lodash<4.17.21, moment, node-serialize, eval())

Supresiones

Si una regla dispara y tienes una razón real para mantener el código, añade un comentario inline en la misma línea:

const publicData: any = response.data // korva-ignore: API externa, sin tipo estático disponible

Un // korva-ignore pelado (sin razón) es a su vez una violación — Sentinel te obliga a escribir por qué estás suprimiendo.

Instalador de hooks

korva sentinel install

Crea / reemplaza:

• .git/hooks/pre-commit Ejecuta korva sentinel run --hook=pre-commit. Si korva no está en el $PATH, el hook imprime un warning y deja pasar el commit — degradación con normalidad, nunca bloquea a nuevos contributors.
• .git/hooks/post-commit No bloquea, ejecuta korva sync --vault --quiet. Se usa para empujar observaciones a Hive cuando está activo.

Arquitectura

sentinel/
├── validator/
│   ├── cmd/korva-sentinel/main.go    → entry, flags, dispatch
│   └── internal/
│       ├── rules/                    → implementaciones Go de cada regla
│       └── analyzer/                 → generación de reportes text/json
├── hooks/
│   ├── pre-commit
│   ├── post-commit
│   └── install.sh
└── rules/
    └── AGENTS.md                     → documentación canónica de cada regla

¿Por qué un gate pre-commit?

La IA genera código rápido. La revisión de código es lenta. La ventana entre “la IA escribió el código” y “PR abierto” es donde se cuelan los malos patrones. Sentinel cierra esa ventana — el developer ve la violación al instante, en su propia máquina, antes de que salga de su rama.

Siguiente

• Workflow de Forge SDD — Sentinel corre como parte de la fase Verify
• Referencia de reglas de Sentinel — cada regla con ejemplos
• Self-hosting — ejecutar Sentinel en CI