pre-push-guard

Un único comando que ejecuta toda la suite de validación local del toolkit sobre los archivos modificados — para evitar que llegue a CI un push que ya se sabía roto.

Es un orquestador: no duplica lógica de [[yaml-control]], [[md-lint-fix]] ni de los tests. Los invoca en orden, sobre el diff real (git diff --name-only origin/<branch>...HEAD + working tree), y agrega los resultados.

Alcance y permisos

No declara allowed-tools, y es deliberado: ese campo preaprueba herramientas —se salta la confirmación durante el turno que invoca el skill— en vez de limitarlas. Declararlo aquí no acotaría nada: quitaría la confirmación del usuario. disallowed-tools sí retira herramientas del pool mientras el skill está activo, y ahí es donde se acota de verdad.

Escribe en .git/hooks/.

Cuándo invocar este skill

Triggers explícitos:

• "valida antes de pushear"
• "chequea todo antes del push"
• "pre-push"
• "guard antes de push"
• "corre todos los checks"
• "lint completo antes de subir"

Triggers proactivos:

• Justo antes de ejecutar git push cuando hay cambios sin pushear.
• Cuando el usuario menciona que "CI estuvo rojo por X" y X es lint/tests — invocar pre-push-guard antes del siguiente push.

Cómo se invoca

python ~/.claude/skills/pre-push-guard/pre_push_guard.py

Modos:

# Todos los archivos rastreados (no solo el diff)
python .../pre_push_guard.py --all

# Saltar tests (solo lint)
python .../pre_push_guard.py --no-tests

# Saltar lint (solo tests)
python .../pre_push_guard.py --no-lint

# Output JSON
python .../pre_push_guard.py --json

# Instalar como git hook (opt-in)
python .../pre_push_guard.py --install-hook

# Desinstalar el hook
python .../pre_push_guard.py --uninstall-hook

Importante: el hook NO se instala automáticamente. Hay que pasar --install-hook explícitamente.

Exit codes:

• 0 — todos los checks pasaron.
• 1 — al menos un check falló → bloquea el push.
• 2 — error de invocación (no es un repo git, etc.).

Qué hace exactamente, en orden

1. Detecta el diff:
   git diff --name-only origin/<current-branch>...HEAD
   + git diff --name-only HEAD       (cambios staged + unstaged)
   + git ls-files --others --exclude-standard  (archivos nuevos)

2. Particiona el diff por extensión:
   - *.yml / *.yaml  → yaml-control
   - *.md            → md-lint-fix --check
   - *.py            → trigger para pytest si existe tests/

3. Ejecuta los pasos en orden, abortando al primer error:
   [a] yaml-control sobre los YAML del diff
   [b] md-lint-fix --check sobre los .md del diff (no auto-fix — solo reporta)
   [c] pytest si hay .py en el diff y existe tests/

4. Reporta resumen unificado con:
   - cuántos archivos vio cada step
   - cuánto tardó cada uno
   - qué falló y cómo arreglarlo

Qué NO hace / limitaciones

• No hace auto-fix. Por diseño — la idea es bloquear, no modificar. Si quieres auto-fix de markdown, corre md-lint-fix por separado antes.
• No instala dependencias. Si pytest no está en el entorno y hay .py en el diff, te avisa y aborta. No instala silenciosamente nada.
• No reemplaza CI. Es un pre-flight check, no la verdad. CI sigue siendo la fuente de verdad.
• No corre security-audit. Audit es pesado y opt-in. Si quieres incluirlo, invócalo a mano.
• El hook git ignora --no-tests / --no-lint. El hook siempre corre la suite completa — esos flags solo aplican a invocación manual.

Dependencias

Si los skills hermanos no están instalados, pre-push-guard degrada con un warning explícito — no falla.

Ejemplos de salida

Caso OK

pre-push-guard — repo: C:/dev/claude-skills-toolkit
  rama: main · base: origin/main
  diff: 4 archivos (.github/workflows/ci.yml, README.md, skills/foo/main.py, tests/test_foo.py)

[1/3] yaml-control · 1 archivo
  ✓ .github/workflows/ci.yml
  (0.8s)

[2/3] md-lint-fix --check · 1 archivo
  ✓ README.md
  (0.3s)

[3/3] pytest · 8 tests
  ✓ 8 passed
  (1.2s)

✅ Todo verde. OK para `git push` (2.3s total).

Exit 0.

Caso con falla

pre-push-guard — repo: C:/dev/foo
  rama: feat/auth · base: origin/main
  diff: 3 archivos (compose.yml, src/auth.py, tests/test_auth.py)

[1/3] yaml-control · 1 archivo
  ✗ compose.yml — sintaxis YAML inválida (línea 14)
  (0.4s)

❌ Bloqueado en step [1/3]. Arregla y vuelve a intentar.
   Detalles arriba ↑

Exit 1. No corre los pasos siguientes — fail-fast.

Instalación como git hook

cd /tu/repo
python ~/.claude/skills/pre-push-guard/pre_push_guard.py --install-hook

Esto crea .git/hooks/pre-push (o lo respalda si ya existe como .pre-push.bak). El hook llama al skill antes de cada git push. Si falla, el push se aborta.

Para desinstalar:

python ~/.claude/skills/pre-push-guard/pre_push_guard.py --uninstall-hook

Restaura el backup si existe; si no, elimina el hook.

El hook se puede saltar con git push --no-verify (estándar de git) en caso de emergencia.

Integración con otros skills

[[yaml-control]]   — la capa 1
[[md-lint-fix]]    — la capa 2 (modo check)
[[security-audit]] — NO incluido (demasiado pesado para pre-push)