Verificación local

HECATE no usa CI en la nube. No hay .github/workflows/, ni CircleCI, ni GitLab CI. La calidad se garantiza en la máquina de quien escribe el código, con dos scripts del repositorio.

1. Por qué

La contrapartida aceptada: no hay una "insignia verde" pública generada por un servicio externo. La insignia del README es un SVG local (docs/badges/local-verify.svg) que documenta el modelo elegido, no un semáforo remoto.

2. Requisitos

Plano de datos (Python)

• Python 3.10 o superior.
• Dependencias de desarrollo:

python -m venv .venv
source .venv/bin/activate          # Windows (PowerShell): .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

[dev] instala ruff, mypy, pytest, pytest-cov y grpcio-tools.

Plano de control (Rust)

• Rust 1.88 o superior (edición 2024; lo exige tonic-prost 0.14).

# Windows: target GNU + linker de MinGW, sin Visual Studio
winget install Rustlang.Rustup
rustup default stable-x86_64-pc-windows-gnu
winget install BrechtSanders.WinLibs.POSIX.MSVCRT

# Linux / macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Si no tienes toolchain Rust, SKIP_RUST=1 ./scripts/verify.sh ejecuta solo el plano de datos (útil para editar documentación o el modelo). El hook pre-push no lo salta.

3. scripts/verify.sh

./scripts/verify.sh

Veintiuno pasos, en orden y con aborto al primer fallo:

Los lints de Rust no son opcionales: el workspace declara [workspace.lints.rust] unsafe_code = "forbid", missing_docs = "deny" y [workspace.lints.clippy] all = "deny". Un #[allow] sin justificación se detecta en revisión.

El paso 17 merece una aclaración: comprueba el laboratorio sin ejecutarlo, porque la verificación obligatoria tiene que funcionar en una máquina sin Docker. Que los contenedores arranquen y que los siete pasos del failover pasen no está verificado aquí, y así se declara en docs/benchmarks/docker-lab.md.

Salida esperada:

HECATE · verificación local
  raíz:   /ruta/a/HECATE
  rama:   main
  commit: 1a2b3c4
  python: .venv/bin/python (Python 3.14.6)
  cargo:  cargo (cargo 1.99.1 (5f94df478 2026-08-27))

[1/21] ruff check · lint del plano de datos
  ✔ sin avisos de lint
...
[6/21] paridad de cuantización · el fixture coincide con el algoritmo de Python
  ✔ el fixture de paridad de cuantización está al día
[7/21] paridad de aceleración · el fixture coincide con el ADR 0001
  ✔ el fixture de paridad de aceleración está al día
[8/21] cargo fmt --check · formato de Rust
  ✔ formato consistente
[9/21] cargo clippy · lints del workspace (warnings = error)
  ✔ clippy limpio
[10/21] cargo clippy::pedantic · sin avisos no justificados
  ✔ pedantic limpio
[11/21] cargo test · suite del plano de control (Rust + Tokio)
  ✔ tests de Rust en verde
[12/21] cargo build --release · binario hecate-node
  ✔ binario de release compilado y enlazado
[17/21] laboratorio Docker · coherencia estática (no se ejecuta)
  ✔ laboratorio Docker coherente
[18/21] métricas · la documentación coincide con el recuento
  ✔ cifras alineadas en README, llms.txt, ai.txt y el sitio
[19/21] CSS · toda clase del HTML tiene regla
  ✔ toda clase del HTML tiene regla CSS
[21/21] documentación · README y docs

TODO EN VERDE — plano de datos (Python) y plano de control (Rust) verificados
la rama puede publicarse (hook pre-push satisfecho)

Variables de entorno

Ejemplos:

COVERAGE_MIN=85 ./scripts/verify.sh
PYTHON=/usr/bin/python3.12 ./scripts/verify.sh
SKIP_RUST=1 ./scripts/verify.sh          # solo plano de datos
SKIP_PYTHON=1 ./scripts/verify.sh        # solo plano de control
SKIP_RUST=1 SKIP_PYTHON=1 ./scripts/verify.sh   # solo SCM y documentación

Códigos de salida

• 0: todo en verde.
• 1: algún paso ha fallado (el mensaje indica cuál: VERIFICACIÓN FALLIDA (código 1, paso 3/21)).
• 101: fallo de cargo (compilación, clippy o test). El paso indica cuál.
• 127/mensaje de intérprete: no se encontró Python o cargo; exporta PYTHON=... / CARGO=....

4. scripts/install-hooks.sh

./scripts/install-hooks.sh            # instala o reinstala el hook
./scripts/install-hooks.sh --force    # sobrescribe un pre-push ajeno (guarda .bak)
./scripts/install-hooks.sh --remove   # desinstala el hook

Escribe .git/hooks/pre-push (o core.hooksPath si está configurado) con este comportamiento:

1. Localiza la raíz del repositorio.
2. Guarda en un temporal las líneas que git pasa por stdin. Hacen falta dos consumidores —el guardián de etiquetas y el cálculo de qué planos se han tocado— y un flujo no se lee dos veces: leerlo mal deja al segundo con una entrada vacía que parece «no hay nada que verificar».
3. Ejecuta scripts/tag-guard.sh: rechaza publicar una etiqueta vX.Y.Z que no apunte al commit publicado (o a un ancestro suyo, para permitir recolocar una etiqueta histórica).
4. Calcula qué planos ha tocado el push comparando la base con la punta, y apaga el que no ha cambiado. Es conservador a propósito: una referencia nueva, un borrado, un git diff que falle o una lista vacía dejan los dos planos encendidos.
5. Verifica que scripts/verify.sh es ejecutable y lo ejecuta con SKIP_PYTHON, SKIP_RUST y VERIFY_HOOK=1. Si falla, aborta el push.

4.bis Por qué el push de documentación no recompila Rust

Verificar los dos planos en cada push significa compilar el workspace para publicar un cambio de una coma en un .md. Eso paga dos veces por una garantía que ya se pagó: si el push no toca crates/, el árbol de Rust es el mismo que ya pasó estas puertas.

La fila de scripts/ no es un descuido: el instrumento que mide no se valida a sí mismo. Si cambia verify.sh, count-tests.sh o un guarda, la medición se repite entera con el instrumento nuevo.

Medido: un push que sólo toca documentación y scripts/ pasó de ~10 min a 10,1 s cuando se saltaron los dos planos. Un push que toca scripts/ sigue tardando lo que tiene que tardar (~3 min), porque ahí sí hay que remirarlo todo.

Si algún día hace falta publicar sin verificar (caso de fuerza mayor), existe git push --no-verify; el README y este documento recomiendan no usarlo.

Windows

Los hooks de git se ejecutan con el intérprete de shell disponible. En Windows funciona con Git Bash (incluido con Git for Windows):

& "C:\Program Files\Git\bin\bash.exe" .\scripts\install-hooks.sh
& "C:\Program Files\Git\bin\bash.exe" .\scripts\verify.sh

verify.sh añade al PATH tanto ~/.cargo/bin como el mingw64/bin de WinLibs si los encuentra, así que funciona lanzado desde un shell no interactivo (que es como git ejecuta los hooks).

Si tu consola no tiene bash, ejecuta los mismos comandos de la tabla del apartado 3 a mano: son exactamente los que llama verify.sh.

5. Refuerzo opcional con pre-commit

.pre-commit-config.yaml declara un único hook local que invoca scripts/verify.sh en la fase pre-push. No descarga nada de la red ni depende de servicios externos.

pip install pre-commit
pre-commit install --hook-type pre-push

Es una alternativa, no un sustituto: si no tienes pre-commit, el hook de install-hooks.sh hace lo mismo con cero dependencias.

6. Flujo recomendado antes de publicar

python -m ruff check --fix .     # arregla lo automático
python -m ruff format .          # formatea Python
cargo fmt --all                  # formatea Rust
./scripts/verify.sh              # verifica los dos planos
git add -A
git commit -m "feat: ..."
git push                         # el hook vuelve a verificar (red de seguridad)

7. Resolución de problemas

8. Qué NO se verifica aquí

• Rendimiento: la latencia real depende del hardware; se mide con docs/benchmarks/methodology.md, no en verify.sh.
• Seguridad de dependencias: ejecuta cargo audit / pip-audit aparte.
• Interoperabilidad entre máquinas: los tests cubren el protocolo en loopback; una prueba entre dos equipos es manual (y recomendable antes de una release).
• Calidad del modelo: los fragmentos se inicializan con una semilla. La verificación comprueba que las matemáticas y el contrato son correctos, no que el modelo sea bueno.