BEKO2210/SkillQuarry

Cordon — envelopes de mudança determinísticos

Cordon é uma camada de aceitação pós-execução para mudanças feitas por agentes de codificação. Ele captura o HEAD atual do Git, registra um caminho relativo ao repositório e uma política de tamanho explícita, e só aceita o resultado quando as mudanças visíveis pelo Git permanecem dentro da política e todos os verificadores independentes saem com código zero.

Use Cordon quando “o agente deve tocar apenas em X” precisar ser verificado por código, e não apenas lembrado pelo agente. Não chame Cordon de sandbox: arquivos ignorados estão fora de seu modelo de evidência v1, e um processo com acesso irrestrito ao sistema de arquivos pode adulterar o estado do próprio Cordon.

Escolha um modo

Neutro em relação ao fornecedor: armar, executar qualquer agente, verificar

cordon arm "atualizar apenas o 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"

# Execute o agente de codificação você mesmo.
cordon check

Este modo nunca invoca um serviço de IA.

Wrapper para Claude Code

cordon run "Corrigir a regressão do parser sem alterar arquivos gerados." \
  --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 inicia um novo processo claude -p com saída JSON, persistência de sessão desabilitada e modo de permissão acceptEdits. Uma execução com falha/interrompida pode ser repetida com um novo processo usando cordon resume, mas apenas enquanto as mudanças parciais visíveis pelo Git ainda satisfizerem o envelope armado e o limite de tentativas não tiver sido atingido.

Leia o resultado

Saída	Significado
0	auditoria aceita
2	Cordon recusou a operação ou estado/política é inválido
3	agente/processo terminou, mas a política Git ou um verificador rejeitou o resultado
4	processo Claude encapsulado falhou, expirou ou excedeu o limite de saída capturada

cordon status informa a fase atual e a última auditoria. cordon reset remove apenas .cordon/; ele não reverte, exclui ou faz commit de arquivos do repositório.

Regras da política

• Pelo menos um padrão --allow é obrigatório.
• --deny sempre prevalece sobre --allow.
• Padrões são globs relativos ao repositório do Cordon: * não atravessa /, ** atravessa, e ? corresponde a um caractere que não seja /.
• Cordon rejeita padrões absolutos (/x, ./x), bytes NUL e segmentos de caminho explícitos . / ...
• Mudanças no HEAD são rejeitadas por padrão. Use --allow-commits apenas quando commits forem parte intencional da tarefa.
• Orçamentos são inclusivos: o limite exato é aceito; um a mais é rejeitado.
• Verificadores são analisados com shlex.split e executados diretamente, não através de um shell. Operadores de shell como &&, pipes e redirecionamentos, portanto, não são interpretados.

Estado e recuperação

Cordon armazena o estado em .cordon/ e registra /.cordon/ em .git/info/exclude. Ele nunca edita o .gitignore.

Cordon também se recusa a armar enquanto um arquivo rastreado tiver a flag de índice assume-unchanged ou skip-worktree, porque tal arquivo não pode ser auditado. Limpe a flag com git update-index --no-assume-unchanged <caminho> em vez de contorná-la.

As gravações no estado semântico do Cordon são arquivo-temp + fsync + os.replace. Um inode de sincronização de comprimento zero resolvido através de metadados Git (cordon.lock) é mantido com um bloqueio consultivo do SO; ele não faz parte do estado .cordon/ e nunca é substituído enquanto bloqueado. O bloqueio impede que duas operações do Cordon possuam o mesmo estado do repositório simultaneamente, incluindo armar/configurar mais uma tentativa de agente encapsulado. Uma tentativa do Claude é marcada como running antes do filho iniciar; interrupção por teclado é persista como interrupted; erros do motor são persistidos e podem ser retomados.

O que Cordon prova — e o que não prova

Cordon pode provar, para a linha de base armada e a implementação Git contra a qual executa, que as mudanças rastreadas visíveis pelo Git mais arquivos não rastreados e não ignorados observados no momento da auditoria atendem à sua política e que os processos verificadores configurados saíram com código zero.

Ele não prova:

• que arquivos ignorados não foram tocados;
• que o repositório está seguro contra um processo malicioso capaz de reescrever o estado;
• que um verificador é logicamente correto;
• que permissões/hooks em um runtime de agente não podem ser contornados;
• que o código é seguro apenas porque o diff é pequeno.

Revise o diff após a aceitação. Cordon é uma porta determinística, não um substituto para revisão de código ou sandbox em nível de SO.

Implementação completa e detalhes de limites: README.md. Evidência da fonte: RESEARCH.md. Testes reproduzíveis e limites conhecidos: TEST_REPORT.md.