ralph

[RALPH - ITERAÇÃO {{ITERATION}}/{{MAX}}]

Sua tentativa anterior não gerou a promessa de conclusão. Continue trabalhando na tarefa.

<Propósito> O Ralph é um loop de persistência orientado por PRD que continua trabalhando em uma tarefa até que TODAS as histórias de usuário em prd.json tenham passes: true e sejam verificadas por um revisor. Ele combina persistência de sessão, repetição automática em caso de falha, rastreamento estruturado de histórias e verificação obrigatória antes da conclusão. </Propósito>

<Quando_Usar>

• A tarefa exige garantia de conclusão com verificação (não apenas "faça o seu melhor")
• O usuário diz "ralph", "não pare", "deve ser concluído", "finalize isso" ou "continue até terminar"
• O trabalho pode abranger múltiplas iterações e precisa de persistência entre repetições
• A tarefa se beneficia de execução estruturada orientada por PRD com aprovação do revisor </Quando_Usar>

<Quando_Não_Usar>

• O usuário quer um pipeline autônomo completo da ideia ao código — use a skill autopilot
• O usuário quer explorar ou planejar antes de se comprometer — use a skill plan
• O usuário quer uma correção rápida e única — delegue diretamente a um agente executor
• O usuário quer controle manual sobre a conclusão — delegue diretamente a um agente executor
• O usuário já tem um /goal ativo do Claude Code e quer apenas monitorar esse loop de meta nativo — adote o /goal existente explicitamente ou use apenas notas de Ultragoal baseadas em artefato, em vez de iniciar o Ralph como um loop de persistência concorrente </Quando_Não_Usar>

<Por_Que_Isso_Existe> Tarefas complexas frequentemente falham silenciosamente: implementações parciais são declaradas "concluídas", testes são ignorados, casos extremos são esquecidos. Ralph previne isso:

1. Estruturando o trabalho em histórias de usuário discretas com critérios de aceitação testáveis (prd.json)
2. Iterando história por história até que cada uma passe
3. Rastreando progresso e aprendizados entre iterações (progress.txt)
4. Exigindo verificação fresca do revisor contra critérios de aceitação específicos antes da conclusão </Por_Que_Isso_Existe>

<Modo_PRD> Por padrão, o ralph opera em modo PRD. Um scaffold prd.json é gerado automaticamente quando o ralph inicia, se nenhum existir. O estado PRD transitório ativo tem escopo de sessão em .omc/state/sessions/{sessionId}/prd.json quando um ID de sessão está disponível; arquivos legados prd.json / .omc/prd.json no nível do projeto são lidos como entradas de migração na inicialização.

Gate de inicialização: Ralph sempre inicializa e valida prd.json na inicialização. O texto legado --no-prd é sanitizado do prompt para compatibilidade reversa, mas não ignora mais a criação ou validação do PRD.

Opt-out de deslop: Se {{PROMPT}} contém --no-deslop, ignore o passe de deslop obrigatório pós-revisão. Use isso apenas quando o passe de limpeza estiver intencionalmente fora do escopo da execução.

Seleção de revisor: Passe --critic=architect, --critic=critic ou --critic=codex no prompt do Ralph para escolher o revisor de conclusão para aquela execução. architect permanece o padrão.

Detecção e reconciliação de estado obsoleto (#3669): Se um PRD for deixado incompleto por uma saída anormal/não-Passo 8 (crash, força-parada, cancelamento antes de /oh-my-claudecode:cancel, fim de sessão), Ralph exibe um [AVISO DE PRD OBSOLETO] explícito na inicialização/retomada, no contexto de continuação e no fim da sessão — com contagens de itens não finalizados, idade do último toque e sinais de ponteiro obsoleto (branchName do PRD mesclado/removido). A conclusão NUNCA é inferida apenas do status PR/branch/merge; o estado do git é apenas um sinal de aviso. Uma história é reconciliada automaticamente para passes: true SOMENTE quando o PRD carrega evidências observáveis configuradas e todas as verificações passam:

{
  "reconciliation": {
    "staleAfterMs": 7200000,
    "observableChecks": {
      "US-001": [
        { "type": "fileContains", "path": "src/landed.ts", "pattern": "LANDED_SYMBOL" },
        { "type": "gitGrep", "ref": "origin/dev", "pattern": "LANDED_SYMBOL" }
      ]
    }
  }
}

Tipos de verificação: fileExists / fileContains (árvore de trabalho) e gitGrep (conteúdo em um ref — isso é "verificado por conteúdo no trunk", nunca status de PR). Histórias sem verificações configuradas nunca são marcadas automaticamente. Histórias reconciliadas mantêm architectVerified: false e ainda exigem verificação do revisor no Passo 7 antes do Passo 8; toda decisão é anexada ao log de auditoria prd-reconciliation.jsonl e resumida nas notas da história. </Modo_PRD>

<Emendas_de_Critério_PRD> Os critérios de aceitação são a autoridade de conclusão do PRD: o Passo 4 verifica CADA critério ativo e o Passo 7 revisa contra eles. Um critério pode deixar de governar SOMENTE através do caminho de emenda com preservação de evidência — nunca por exclusão silenciosa ou por "satisfazer" uma medição de critério que foi refutada.

Quando a implementação prova que um critério é empiricamente falso (ex: uma contagem no briefing de despacho está errada), emende-o:

1. Substitua o critério refutado pela correção medida, ou substitua quando nenhuma substituição governa.
2. Registre a emenda no livro-razão criterionAmendments da história. O texto do critério original é retido textualmente (nunca reescrito ou excluído) junto com:
   • kind: "replaced" ou "superseded"
   • original: o critério refutado textual (deve ainda estar ativo quando a emenda é registrada)
   • replacement: o critério corrigido (apenas para replaced)
   • reason: por que o original não governa mais
   • evidence: a medição limitada que o refutou (ex: "enumerou 12 setters, não 16: ...")
   • authority: quem fez a emenda (use o id da sessão ralph)
   • timestamp: timestamp ISO 8601
3. A verificação de conclusão então verifica apenas os critérios ATIVOS; o livro-razão mantém a trilha de auditoria para que revisores vejam por que o original não governa mais.

Regras:

• Uma emenda sem evidência limitada, razão, autoridade ou timestamp é inválida — o PRD falha fechado na leitura em vez de ser silenciosamente enfraquecido.
• Um original que ainda está ativo não pode ser emendado; um original pode ser emendado apenas uma vez.
• Caminho programático: amendCriterion(dir, storyId, { original, replacement, reason, evidence, authority }) e supersedeCriterion(dir, storyId, { original, reason, evidence, authority }).
• PRDs editados manualmente devem preservar os mesmos invariantes; um livro-razão contraditório (original ainda ativo, ou emendado duas vezes) torna o PRD inválido.
• Isso não é uma ferramenta de enfraquecimento de meta: existe para que "a medição discorda do plano" resolva em direção à medição sem que o loop perca sua aderência. </Emendas_de_Critério_PRD>

<Política_de_Execução>

• Dispare chamadas de agentes independentes simultaneamente — nunca espere sequencialmente por trabalho independente
• Use run_in_background: true para operações longas (instalações, compilações, suítes de teste)
• Sempre passe o parâmetro model explicitamente ao delegar para agentes
• Leia docs/shared/agent-tiers.md antes da primeira delegação para selecionar os níveis de agente corretos
• Entregue a implementação completa: sem redução de escopo, sem conclusão parcial, sem excluir testes para fazê-los passar
• Se um /goal do Claude Code for mencionado, trate-o apenas como um handoff/fonte de evidência de loop de sessão nativo e use as políticas de conflito determinísticas refuse, adopt_existing e artifact_only em vez de tratamento de aviso não-determinístico. Ralph permanece a autoridade do loop OMC para esta execução; não afirme que /goal executou testes ou leu arquivos independentemente, e não trate o sucesso do avaliador como um substituto para a verificação do revisor Ralph. </Política_de_Execução>

2. Escolha a próxima história: Leia o arquivo PRD ativo e selecione a história de maior prioridade com passes: false. Este é seu foco atual.

3. Implemente a história atual:

   • Delegue a agentes especialistas nos níveis apropriados:
     • Consultas simples: nível LOW (Haiku) — "O que esta função retorna?"
     • Trabalho padrão: nível MEDIUM (Sonnet) — "Adicione tratamento de erro a este módulo"
     • Análise complexa: nível HIGH (Opus) — "Depure esta condição de corrida"
   • Se durante a implementação você descobrir subtarefas, adicione-as como novas histórias ao arquivo PRD ativo
   • Execute operações longas em segundo plano: Compilações, instalações, suítes de teste usam run_in_background: true

4. Verifique os critérios de aceitação da história atual: a. Para CADA critério de aceitação ativo na história, verifique se ele é atendido com evidência fresca b. Execute verificações relevantes (teste, compilação, lint, typecheck) e leia a saída c. Se a implementação provar que um critério é empiricamente FALSO (a medição o refuta), NÃO marque a história como completa e NÃO exclua ou enfraqueça silenciosamente o critério. Em vez disso, emende-o através do caminho de preservação de evidência descrito em <Emendas_de_Critério_PRD>: substitua ou supere-o nos critérios ativos e anexe o original (textualmente) com kind, reason, evidence, authority e timestamp ao livro-razão criterionAmendments da história. Em seguida, continue verificando os critérios ATIVOS restantes d. Se algum critério ativo NÃO for atendido e NÃO emendado, continue trabalhando — NÃO marque a história como completa

5. Marque história como completa: a. Quando TODOS os critérios de aceitação ativos forem verificados, crie uma reivindicação de conclusão vinculada à revisão: defina passes: true e defina completionCriteriaRevision para a governingCriteriaRevision atual da história. Não defina architectVerified; a aprovação do revisor vincula isso separadamente. b. Registre o progresso em progress.txt: o que foi implementado, arquivos alterados, aprendizados para iterações futuras c. Adicione quaisquer padrões de codebase descobertos a progress.txt

6. Verifique a conclusão do PRD: a. Leia o arquivo PRD ativo — TODAS as histórias estão marcadas como passes: true (sem critérios ativos restantes não verificados)? b. Se NÃO estiverem todas completas, volte ao Passo 2 (escolha a próxima história) c. Se TODAS estiverem completas, prossiga ao Passo 7 (verificação do arquiteto)

7. Verificação do revisor (em níveis, contra critérios de aceitação):

   • <5 arquivos, <100 linhas com testes completos: nível STANDARD mínimo (architect-medium / Sonnet)
   • Alterações padrão: nível STANDARD (architect-medium / Sonnet)

   • 20 arquivos ou alterações de segurança/arquitetura: nível THOROUGH (architect / Opus)

   • Se --critic=critic, use o agente critic do Claude para o passe de aprovação
   • Se --critic=codex, execute omc ask codex --agent-prompt critic "..." para o passe de aprovação. O prompt do crítico Codex DEVE incluir:
     1. A lista completa de critérios de aceitação do prd.json para verificação
     2. Uma diretiva para avaliar se a implementação é ÓTIMA — não apenas correta, mas se existe uma abordagem significativamente melhor (mais simples, mais rápida, mais sustentável) que a implementação perdeu
     3. Uma diretiva para revisar todo o código relacionado às alterações (chamadores, chamados, tipos compartilhados, módulos adjacentes), não apenas os arquivos diretamente modificados
     4. A lista de arquivos alterados durante a sessão ralph para contexto
   • Piso Ralph: sempre pelo menos STANDARD, mesmo para alterações pequenas
   • O revisor selecionado verifica contra os critérios de ACEITAÇÃO ESPECÍFICOS do prd.json, não "está concluído?" vago
   • Na APROVAÇÃO: prossiga imediatamente para o Passo 7.5 no mesmo turno. NÃO pause para relatar o veredito ao usuário — o relatório acontece apenas no Passo 8 (/oh-my-claudecode:cancel) ou na rejeição (Passo 9). Tratar um veredito aprovado como um ponto de verificação de relatório é um antipadrão de parada educada.

7.5 Passe de Deslop Obrigatório (executa incondicionalmente após a aprovação do Passo 7, a menos que {{PROMPT}} contenha --no-deslop):

• Invoque a skill ai-slop-cleaner através da ferramenta Skill: Skill("oh-my-claudecode:ai-slop-cleaner") — é uma Skill, não um agente. Se você chamá-la erroneamente via Task(subagent_type="oh-my-claudecode:ai-slop-cleaner"), o hook PreToolUse do OMC nega a chamada com o identificador correto da ferramenta Skill; não substitua por um agente de nome similar. Execute no modo padrão (não --review) apenas nos arquivos alterados durante a sessão Ralph atual.

• Mantenha o escopo limitado ao conjunto de arquivos alterados pelo Ralph; não amplie o passe de limpeza para arquivos não relacionados.

• Se o revisor aprovou a implementação, mas o passe de deslop introduz edições de acompanhamento, mantenha essas edições dentro do mesmo escopo de arquivo alterado antes de prosseguir.

  7.6 Re-verificação de Regressão:

• Após o passe de deslop, execute novamente todos os testes, compilações e verificações de lint relevantes para a sessão Ralph.

• Leia a saída e confirme que a execução de regressão pós-deslop realmente passa.

• Se a regressão falhar, reverta as alterações do cleaner ou

... [truncado para tradução]