Volver a la wiki

Runbook · cambios seguros del harness (claude-method)

Runbook · cambios seguros del harness

Cuándo usarlo: ANTES de cualquier commit a claude-method que toque plugins/*/hooks/hooks.json, sus scripts Python, los checks de harness/*.py, o docs compartidos entre repos (CLAUDE.md). Nacido de la mañana del 05-08-2026: tres incidentes cruzados (sesión de Txell sin shell, drift de copias de 35 días, numeración de reglas divergente) que costaron una mañana entera de los tres perfiles.

Las 4 leyes del harness distribuido

  1. Los hooks se snapshotean al arranque de sesión. Una sesión viva (o la PRIMERA de un perfil que aún no ha pulleado) invoca las rutas del checkout con el que arrancó — y el pull del SessionStart puede borrarle un fichero bajo los pies a mitad de sesión. Exit ≠ 0 en PreToolUse = deny de Edit/Write/Bash = sesión sin shell. Mitigado desde el 05-08 (claude-method 6aa2a45): los hooks entran por harness/run_hook.py, un entrypoint estable que hace fail-open (exit 0 + aviso stderr) si el script objetivo falta — la política (deny del gate, etc.) sigue intacta porque stdout y exit code del objetivo pasan sin tocar.
  2. El rollout es progresivo, no atómico. 3 perfiles × varias máquinas × 3 repos convergen a destiempo vía pull. Todo cambio debe ser inocuo para quien aún no lo tiene.
  3. Los checks se ejecutan desde la fuente. Desde la fase 2 del Plan A (05-08-2026) claude-method/harness/*.py es la única copia que existe: el pre-commit de cada repo (hook v2) los invoca ahí mismo, con fail-open por fichero. Las copias <repo>/scripts/harness/ se retiraron de Pro y del workspace — ya no hay nada que propagar ni que pueda desincronizarse. Lo que sí puede quedarse atrás es el hook instalado frente a pre-commit.hook; de eso avisa /method-doctor.
  4. La numeración de Reglas es la de CreaRack-Pro/CLAUDE.md. Las tablas de otros repos son parciales con numeración canónica; citar siempre por el número canónico.

Checklist A · mover / renombrar / retirar un script de hook

Desde run_hook.py (05-08-2026) un move ya NO brickea sesiones nuevas: el lanzador hace fail-open si el objetivo falta. Este checklist sigue vigente para (a) snapshots de sesiones/perfiles anteriores al lanzador, que aún invocan rutas directas, y (b) mover el propio run_hook.py — que NO se hace nunca.

  1. Shim exit-0 en la ruta vieja EN EL MISMO COMMIT del move (import sys; sys.exit(0) + comentario con el criterio de retirada).
  2. Probar el script NUEVO por stdin sintético: printf '%s' "$json" | python <ruta-nueva> (el JSON como argumento, nunca dentro del format-string — los backslashes de rutas Windows generan JSON inválido y el test miente). “Probarlo en esta sesión” NO vale: observa el snapshot viejo.
  3. Retirar el shim SOLO cuando /method-status muestre a LOS 3 PERFILES con checkout ≥ el commit del move. Contar “sesiones vivas” NO vale — así se retiró mal el 04-08 y la primera sesión de Txell (perfil sin pullear) se quedó sin shell el 05-08.

Checklist B · cambiar un check del pre-commit (harness/*.py)

  1. Editar SOLO la fuente en claude-method/harness/. No hay copias que propagar ni paridad de copias que verificar: eso murió con la fase 2 del Plan A (05-08-2026).
  2. Verificar con un commit sintético en un repo real: tocar un fichero que dispare el check, git commit, y comprobar que el veredicto es el esperado (bloquea cuando debe, deja pasar cuando debe). El commit de prueba se descarta después.
  3. Ten presente que el efecto es inmediato: el hook lee la fuente en vivo, así que un check roto rompe el commit de los 3 perfiles en cuanto pulleen claude-method. Un check nuevo, igual — no hace falta que nadie reinstale nada.

Nota de configuración: el gate de commit de la Biblioteca se arma con .claude/bib-gate.json del repo (report_url obligatoria; skip_log_url opcional — sin ella se omite el skip-log). Proyectos del Iniciador creados entre el 03-08 y el 05-08-2026 (p.ej. demo-init) llevan marcador SIN report_url → su gate de commit está inerte hasta añadir el campo a mano.

Checklist C · docs compartidos entre repos

Verificación final (siempre)

  1. /method-doctor en el perfil propio → VERDE (incluye la paridad del pre-commit instalado vs pre-commit.hook).
  2. /method-status → los 3 perfiles, commit y veredicto.
  3. El vigía semanal de drift (cron OPS harness-drift-check.sh, lunes 07:30 UTC) alerta en el dashboard si un perfil lleva >7 días sin converger con el método movido por delante — desde la fase 2 del Plan A ya no vigila copias, porque no existen. Pero no sustituye la verificación del ciclo: el vigía es la red, no el trapecio.

Historial de incidentes que motivan cada punto

Véase también

Subir