BEKO2210/SkillQuarry

Cordon — envolventes de cambio deterministas

Cordon es una capa de aceptación posterior a la ejecución para cambios realizados por agentes de codificación. Toma una instantánea del HEAD actual de Git, registra una ruta explícita relativa al repositorio y una política de tamaño, y acepta el resultado solo cuando los cambios visibles para Git se mantienen dentro de esa política y cada verificador independiente termina con código cero.

Use Cordon cuando "el agente solo debe tocar X" deba ser verificado por código en lugar de recordado por el agente. No llame a Cordon una caja de arena: los archivos ignorados están fuera de su modelo de evidencia v1, y un proceso con acceso irrestricto al sistema de archivos puede alterar el estado propio de Cordon.

Elija un modo

Neutral al proveedor: armar, ejecutar cualquier agente, verificar

cordon arm "actualizar solo el parser" \
  --allow "src/parser/**" \
  --allow "tests/parser/**" \
  --deny "src/parser/generated/**" \
  --max-files 8 \
  --max-added-lines 400 \
  --max-deleted-lines 200 \
  --verify "python3 -m unittest discover -s tests"

# Ejecute el agente de codificación usted mismo.
cordon check

Este modo nunca invoca un servicio de IA.

Envoltorio para Claude Code

cordon run "Arregle la regresión del parser sin modificar archivos generados." \
  --allow "src/parser/**" \
  --allow "tests/parser/**" \
  --deny "src/parser/generated/**" \
  --verify "python3 -m unittest discover -s tests" \
  --max-files 8 \
  --max-added-lines 400 \
  --max-deleted-lines 200 \
  --max-turns 20 \
  --max-budget-usd 2

Cordon lanza un proceso fresco claude -p con salida JSON, persistencia de sesión deshabilitada y modo de permiso acceptEdits. Una ejecución fallida o interrumpida puede reintentarse con un proceso fresco usando cordon resume, pero solo mientras los cambios parciales visibles para Git aún satisfagan la envolvente armada y no se haya alcanzado el límite de intentos.

Lea el resultado

Salida	Significado
0	auditoría aceptada
2	Cordon rechazó la operación o el estado/política es inválido
3	agente/proceso terminó, pero la política de Git o un verificador rechazaron el resultado
4	el proceso envuelto de Claude falló, excedió el tiempo de espera o superó el límite de salida capturada

cordon status informa la fase actual y la última auditoría. cordon reset elimina solo .cordon/; no revierte, elimina ni confirma archivos del repositorio.

Reglas de política

• Al menos un patrón --allow es obligatorio.
• --deny siempre prevalece sobre --allow.
• Los patrones son globs de Cordon relativos al repositorio: * no cruza /, ** sí lo hace, y ? coincide con un carácter que no sea /.
• Cordon rechaza patrones absolutos (/x, ./x), bytes NUL y segmentos de ruta explícitos . / ...
• El movimiento de HEAD es rechazado por defecto. Use --allow-commits solo cuando los commits sean una parte intencional de la tarea.
• Los presupuestos son inclusivos: el límite exacto se acepta; uno por encima se rechaza.
• Los verificadores se analizan con shlex.split y se ejecutan directamente, no a través de un shell. Por lo tanto, los operadores de shell como &&, tuberías y redirecciones no se interpretan.

Estado y recuperación

Cordon almacena el estado en .cordon/ y registra /.cordon/ en .git/info/exclude. Nunca edita .gitignore.

Cordon también se niega a armar mientras un archivo rastreado tenga la marca de índice assume-unchanged o skip-worktree, porque dicho archivo no puede auditarse. Limpie la marca con git update-index --no-assume-unchanged <ruta> en lugar de evitarlo.

Las escrituras en el estado semántico de Cordon son archivo temporal + fsync + os.replace. Un inodo de sincronización de longitud cero resuelto a través de metadatos de Git (cordon.lock) se mantiene con un bloqueo de asesoramiento del SO; no es parte del estado de .cordon/ y nunca se sustituye mientras está bloqueado. El bloqueo evita que dos operaciones de Cordon posean el mismo estado del repositorio simultáneamente, incluido armado/configuración más un intento de agente envuelto. Un intento de Claude se marca como running antes de que el hijo comience; la interrupción por teclado se persiste como interrupted; los errores del motor se persisten y pueden reanudarse.

Lo que Cordon prueba — y lo que no

Cordon puede probar, para la línea base armada y la implementación de Git contra la que se ejecuta, que los cambios rastreados visibles para Git más los archivos no ignorados y no rastreados observados en el momento de la auditoría cumplen con su política y que los procesos verificadores configurados salieron con código cero.

No prueba:

• que los archivos ignorados no fueron tocados;
• que el repositorio es seguro contra un proceso malicioso capaz de reescribir el estado;
• que un verificador es lógicamente correcto;
• que los permisos/ganchos en un tiempo de ejecución del agente no puedan ser eludidos;
• que el código sea seguro solo porque el diff es pequeño.

Revise el diff después de la aceptación. Cordon es una puerta determinista, no un reemplazo para la revisión de código o el sandboxing a nivel de SO.

Detalles completos de implementación y límites: README.md. Evidencia de fuente: RESEARCH.md. Pruebas reproducibles y límites conocidos: TEST_REPORT.md.