Qué guardas existen, qué impide cada una y cómo se diseñan para que no se degraden.
Implementado. La lista es la de las guardas que están en el repositorio; cada tabla dice cuáles corren en CI y cuáles son locales u operativas. Dos guardas más (
check:docs-contractycheck:headless-parity) son parte del ADR de documentación como contrato, que está propuesto: no se describen aquí como obligatorias hasta su bloqueo, y su estado está en la vista del roadmap.
Una guarda es una decisión convertida en código que falla. Para que no se degrade:
catch {} en un parser, un
@ptrCast sin comentario, una ruta sin policy…) y su salida cruda.safety_baseline.zon, check-consumer.baseline.json) que puede encogerse y nunca crecer; un
fichero nuevo parte de cero. Bajar el baseline es un commit explícito..github/workflows/guard.yml (directamente, dentro de check:roadmap o dentro
de bun run test) o a zig build / zig build test, salvo las que se marcan como
locales u operativas: necesitan Docker, root o la infraestructura levantada, y su
resultado sólo cuenta como evidencia con la salida cruda adjunta al ticket.bun run check:roadmap ejecuta de una vez estas comprobaciones y dice cuáles fallan. Corre en CI
como paso propio del job ssot-and-foundation:
| Comprobación | Qué impide |
|---|---|
roadmap-consistency | Que el spec congelado se desvíe de su integridad interna; el contador agregado de gates (r31 D1) |
check:roadmap-view | Que ROADMAP.md (vista generada) quede viejo respecto de styx.model.yml |
context-consistency | Que los CLAUDE.md y las reglas se desvíen del árbol real, o que congelen estado |
axon-gen --check | Que las vistas generadas queden viejas respecto de su fuente |
check-config | Que la configuración de axon no cumpla su esquema |
check-model | Que el model rompa sus reglas: tipos de nodo, forma de los ids, zonas, autoridad única |
check-gates | Que un gate se «autore» en verde sin evidencia (ver abajo) |
check-consumer | Que aparezcan exportaciones nuevas sin ningún consumidor (principio anti-especulativo) |
docs-views --check | Que las vistas roadmap/ y decisiones/ de esta documentación queden viejas respecto del model |
check-docs-contract | Que una página de esta documentación contradiga el model, los manifests de gate o los ADR que cita (ver páginas de contrato) |
check-headless-parity | Que la web ofrezca algo que no exista también sin interfaz: operación, OpenAPI, SDK y CLI |
check-gates hace dos cosas, en este orden: congela la clase de cada gate para impedir
reclasificaciones silenciosas (reclasificar es editar un baseline visible en el cambio), y exige
que un gate se derive de un manifiesto de evidencia: todo item que no esté abierto debe tener
un comando ya ejecutado, su salida, y un autor distinto del verificador. El veredicto es por
item, nunca un contador agregado.
| Guarda | Qué impide |
|---|---|
check:bus | Que la tabla BUS_ROUTES, el espejo Zig y la ACL de NATS se desvíen: lo versionado debe ser lo generado |
test:bus-acl | Que un servicio publique o se suscriba fuera de su tabla, o cree o cambie un stream, sobre un NATS real |
| Test de transporte directo | Que algo fuera de @styx/bus importe NATS o los transportes de spire |
| Test de imports | Que packages/ importe de apps/ (con la excepción documentada del tipo del cliente) |
| Guarda | Qué impide |
|---|---|
audit:safety | Primitivas en bruto en el daemon (rutas, sincronización, errores tragados, abortos, casts); incluye Z1 |
check:zkit-no-reimpl | Reimplementar un símbolo de zkit en el daemon |
check:no-media-spawn | Lanzar ffmpeg o ffprobe como proceso desde código de producto |
| Auditoría de imports C15 | Dependencias entre crates que rompan la taxonomía del data plane |
test:zig:tsan | Carreras de datos en el data plane (con un canario que prueba que el carril discrimina) |
| Guarda | Dónde corre | Qué impide |
|---|---|---|
check:supply-chain | CI (paso propio) | Acciones sin fijar por commit, token de CI con escritura, Bun distinto del fijado, instalaciones sin lockfile congelado, curl sin hash, toolchain sin fijar |
check:deploy | CI (dentro de bun run test) | Un compose que se salga del endurecimiento: contenedores, redes, secretos, borde, direcciones de confianza |
check:deploy-render | CI (dentro de los tests de apps/cli) | Que el compose versionado de deploy/ deje de ser el render de deploy/model/styx.deploy.yml |
check:docker-context | CI (paso propio) | Un Dockerfile que no se pueda construir desde un checkout limpio (un COPY de algo que ya no existe) |
check:infra-live | Local u operativa (infra levantada, Docker) | Una infraestructura real que contradiga lo declarado (por ejemplo un puerto alcanzable por donde no debe) |
test:deploy-egress | Local u operativa (Docker y root) | Que un servicio llegue a donde su política de salida no permite |
| Guarda | Dónde corre | Qué impide |
|---|---|---|
check:release-map | CI (paso propio) | Un fichero de apps/, native/, deploy/ o docker/ sin componente en release/components.yml, o con dos |
check:interfaces | CI (paso propio) | Que cambie el esquema de un contrato entre componentes (bus, socket del daemon) sin subir su versión |
check:migrations | CI (paso propio) | Una migración SQL sin cabecera -- styx:kind=expand|contract|data o que el código del tren anterior no aguante sin declararlo contract |
check:cli-reference | CI (paso propio) | Que apps/cli/REFERENCE.md o las guías de operador mencionen órdenes, opciones o códigos de error que el CLI no tiene, o al revés |
check:licenses | Local (necesita build/release/ de release:build y los SBOM de release:sbom) | Un artefacto de release con una dependencia GPL o AGPL, o con una licencia que pide revisión y no tiene excepción en release/license-policy.json |
release:plan y release:version no son guardas: calculan versiones. Cómo encajan con el resto
del recorrido está en Ciclo de vida.
bun run typecheck, bun run lint y bun run test corren en CI. Los tests incluyen guardas de
arquitectura y de seguridad (rutas sin policy, lecturas de secretos desde el entorno, imports
prohibidos, endurecimiento del despliegue).
bun run format:check valida el formato, pero es local: no corre en CI.
check:vision-ledger (CI, paso propio) valida docs/overview/vision-ledger.yml: esquema, ids
únicos y que cada referencia a un nodo, un ADR o una página exista.
scripts/docs/gen-roadmap-adrs.ts --check regenera en memoria las vistas roadmap/ y
decisiones/ y falla si difieren del contenido versionado o si sobra un fichero (ver
generadores). Corre en CI dentro de check:roadmap (fila docs-views --check),
así que un verdict, un nodo o un ADR cambiado sin bun run docs:gen pone CI en rojo, y una copia
a mano metida en esas carpetas también. Qué se exige de cada página y cómo se cruzan las
páginas con el roadmap está en páginas de contrato.