robcsaszar/crucible

O que crucible faz?

Reconhecimento paralelo de domínio → ataque adversarial → plano → verificação → SPEC → implementação → PR.

Regra de Propriedade de Arquivos

Subagentes NUNCA escrevem arquivos. Eles retornam resultados como texto. Você (o orquestrador) escreve cada artefato. Arquivos são a transferência entre fases — a memória do subagente não é.

Configuração

Analise a invocação para:

• Domínios (obrigatório) — áreas voltadas ao usuário a serem auditadas, ex.: player, curator
• Dica de escopo (opcional) — foco estreito dentro de um domínio, ex.: lobby SSE, role selection

Determine o diretório de saída: .crucible/run-<N>/ onde N é o próximo inteiro não utilizado.

Verificação de execução anterior: escaneie .crucible/ em busca de diretórios de execução existentes. Leia cada findings.json. Alimente seus IDs confirmados como uma lista de ignorados nos agentes da Fase 1 — não redescubra problemas conhecidos e corrigidos; concentre esforço nas lacunas.

Arquivos escritos nesta execução (todos pelo orquestrador):

Arquivo	Fase	Função
codebase-map.md	1	Contexto injetado literalmente em todos os agentes downstream
recon-<dominio>.json	1	Descobertas brutas por domínio
findings.json	1→2→4	Descobertas mescladas; vereditos adicionados a cada fase
PLAN.md	3	Plano de correção priorizado
SPEC.md	5	Código antes/depois + casos de teste por descoberta

Fase 1 — Reconhecimento

LEITURA OBRIGATÓRIA references/recon-phase.md antes de lançar agentes.

Lance um agente de pesquisa por domínio declarado, todos em paralelo. Alimente cada um com: caminho da base de código, nome do domínio, dica de escopo (se houver), IDs conhecidos anteriormente a ignorar.

Os agentes retornam texto JSON. Se um agente retornar prosa em vez de um array JSON, solicite novamente uma vez com o formato exato do esquema de assets/findings-schema.json. Se falhar novamente, escreva um recon-<dominio>.json vazio ([]) e anote a falha em codebase-map.md. Continue — um domínio com falha é recuperável; não aborte a execução.

Colete as respostas válidas e então:

1. Escreva recon-<dominio>.json por resposta de agente
2. Sintetize codebase-map.md — caminhos de arquivo chave, limites de domínio, módulos compartilhados, convenções
3. Mescle todas as descobertas de domínio em findings.json

Critério de conclusão: todo domínio tem um recon-<dominio>.json, codebase-map.md escrito, findings.json escrito. NÃO carregue references/adversarial-phase.md até a Fase 2.

Fase 2 — Revisão Adversarial

LEITURA OBRIGATÓRIA references/adversarial-phase.md antes de lançar agentes.

Lance um agente geral por descoberta (descobertas em lote do mesmo domínio). Cada agente recebe o JSON da descoberta e codebase-map.md — NÃO o raciocínio do agente de reconhecimento. O limite de independência é a barreira de qualidade.

Os agentes retornam CONFIRMADO / REJEITADO / REBAIXADO com evidência de código. Acrescente cada veredito à entrada correspondente em findings.json. Execute node scripts/validate-findings.cjs findings.json — corrija quaisquer erros de esquema antes da Fase 3.

Quando o validador não puder ser executado — node não no PATH, o script ou seu esquema faltando, um erro de uso, ou qualquer falha antes do início da validação (Falha ao carregar esquema, Falha ao analisar JSON) — isso não é uma aprovação. Anote ⚠ descobertas não validadas — validador indisponível: <motivo> na saída das descobertas e no topo da transferência SPEC, depois continue. Uma rejeição de esquema é o caso oposto e sempre bloqueia: corrija as descobertas, execute novamente, não prossiga após uma rejeição. Ambos atualmente saem com código 1, então leia o texto do erro, não o código de saída.

Critério de conclusão: toda descoberta tem um campo adversarial_verdict. A validação do esquema passa. NÃO recarregue references/recon-phase.md deste ponto em diante.

Fase 3 — Síntese do Plano

Verificação de zero descobertas: antes de sintetizar, conte as entradas confirmadas + rebaixadas em findings.json. Se zero, escreva .crucible/run-<N>/REPORT.md com a única linha "Nenhuma descoberta acionável após revisão adversarial." Pare — não abra um PR.

Sintetize as descobertas confirmadas + rebaixadas de findings.json em PLAN.md:

• P1 (crítico/alto): fluxos principais quebrados, perda de dados, desconexão permanente
• P2 (médio): erros visíveis ao usuário, caminhos de recuperação ausentes
• P3 (baixo): polimento, desvios de documentação, problemas de cópia

Agrupe descobertas que compartilham uma causa raiz — uma correção pode eliminar várias. Ao agrupar: a maior gravidade entre as descobertas agrupadas define a prioridade do grupo. Se as descobertas agrupadas tiverem abordagens de correção conflitantes, divida-as — causa raiz compartilhada não requer correção compartilhada. Declare a ordem de correção onde existirem dependências. Descobertas rejeitadas excluídas totalmente.

Critério de conclusão: PLAN.md escrito; toda descoberta confirmada aparece exatamente uma vez.

Fase 4 — Verificação Independente

Lance um agente de pesquisa por descoberta P1 + P2, todos em paralelo. Cada agente recebe a instrução: "Você NÃO escreveu esta descoberta. Verifique cada afirmação factual contra o código-fonte atual."

Cada agente verifica: arquivo existe no caminho, número da linha corresponde ao código descrito, nome do escopo está correto, padrão descrito realmente aparece. Retorna VERIFICADO / CORRIGIDO [campo: errado → certo] / REJEITADO [motivo].

Aplique todas as correções em PLAN.md e findings.json. Execute a validação do esquema novamente. PLAN.md e findings.json devem concordar — nenhuma divergência entre entregáveis.

Critério de conclusão: todas as descobertas P1+P2 verificadas. Todas as correções aplicadas. Esquema passa.

Fase 5 — SPEC

Escreva SPEC.md com uma seção por descoberta confirmada (ordem P1 → P2 → P3):

• Caminho exato do arquivo + intervalo de linhas (verificado)
• Código antes (código-fonte real, não pseudocódigo)
• Código depois (correção concreta)
• Casos de teste: uma frase por comportamento que o teste deve verificar

Execute node scripts/validate-findings.cjs findings.json como verificação final.

Critério de conclusão: toda entrada de PLAN.md tem uma seção SPEC. Validação passa.

Fase 6 — Entrega

1. Atualize os documentos de fluxo (docs/flows/) para qualquer descoberta que altere um comportamento voltado ao usuário
2. Invoque a skill implement com SPEC.md
3. Abra um PR — esta é a barreira de revisão humana; nenhuma aprovação intermediária é solicitada

Corpo do PR: link para PLAN.md, contagem de descobertas por gravidade, link para SPEC.md, lista de documentos de fluxo atualizados.

NUNCA

• NUNCA peça a um subagente para escrever um arquivo Em vez disso: Faça o agente retornar o conteúdo como texto; escreva o arquivo você mesmo. Por quê: O estado entre fases vive em arquivos. Se um agente escrever diretamente, o orquestrador perde a cópia canônica e não pode reconciliar entregáveis após correções da Fase 4.

• NUNCA forneça a cadeia de raciocínio do agente de reconhecimento a um agente adversarial Em vez disso: Passe apenas a descoberta estruturada (JSON) e codebase-map.md. Por quê: Ver a lógica do agente de reconhecimento ancora o agente adversarial nas mesmas suposições — o limite de independência é o que elimina falsos positivos.

• NUNCA prossiga além da Fase 2 com falhas de validação de esquema Em vez disso: Corrija os campos com falha em findings.json antes de sintetizar o plano. Por quê: Um PLANO construído sobre descobertas malformadas produz uma SPEC com caminhos de arquivo e números de linha errados que a skill implement não pode usar.

• NUNCA escreva SPEC.md enquanto qualquer descoberta P1/P2 tiver verification: "pending" Em vez disso: Execute node scripts/validate-findings.cjs findings.json --pre-spec e resolva todas as falhas antes da Fase 5. Por quê: A proteção --pre-spec existe no script validador, mas é invisível a menos que invocada — um agente que ignore esta chamada fará SPEC de caminhos de arquivo não verificados e passará números de linha errados silenciosamente para implement.