hackycy/goal-loop

Goal Loop

Compila documentos de decisão em três artefatos:

• implementation-plan.md: Contrato Gate estável, respondendo o que fazer, os limites, como verificar e quando parar.
• goal-runbook.md: Livro-razão exclusivo de estado de execução e evidências, respondendo apenas onde a execução está e quais evidências existem.
• goal-prompt.md: Ponto de entrada fixo de fácil cópia manual, apontando apenas para os dois primeiros documentos; não vincula Gate nem repete contratos.

Este skill apenas estabelece ou verifica a superfície de controle de execução; não implementa Gates nem refaz decisões já aprovadas.

Localizar Entrada

O usuário fornece um diretório de esforço, map.md, ADR/especificação ou um implementation-plan.md existente. O skill analisa a raiz do repositório Git e localiza o esforço; se não conseguir localizar de forma única, para e lista os caminhos verificados.

Lê os arquivos CLAUDE.md, AGENTS.md, CONTEXT.md / CONTEXT-MAP.md aplicáveis, bem como o mapa, especificação, plano de implementação e seus links locais para ADRs, decisões, issues e dependências de aceitação. CONTEXT.md fornece apenas terminologia e fatos do domínio, não gera Gates isoladamente.

Suporta dois tipos de entrada convergentes:

• Somente Decisões: Gate, escopo, verificação e saída podem ser obtidos de ADRs aceitos, especificações ou issues resolvidas.
• Wayfinder: O campo Not yet specified do mapa está vazio ou explicitamente "nenhum"; todas as decisões que participam da ordem de execução e aceitação estão resolvidas.

Quando há links de decisão local ausentes, ADRs não aceitos, decisões não resolvidas, ou documentos ainda com TBD, TODO, perguntas em aberto, decisões pendentes, o skill para e relata cada lacuna individualmente. Não é permitido preencher decisões de produto, políticas de aceitação ou limites de reversão com base em experiência.

Compilar Plano

Se implementation-plan.md não existir, lê completamente references/implementation-plan-schema.md e gera o plano a partir das decisões convergentes. Se já existir, apenas lê e valida, sem sobrescrever.

O plano detém exclusivamente todos os contratos Gate estáveis: Objetivo, Entradas, Limite de Escopo, Restrições, Política de Fatias, Verificação, Regra de Evidências, Condições de Parada, Rollback e Condições de Saída. Comandos de projeto e restrições técnicas são registrados apenas no plano, não entram no prompt fixo.

Se o plano antigo contiver Current Execution State, pode ser importado uma vez ao inicializar o runbook; os nomes, ordem e estado dos Gates devem ser consistentes, e passed/blocked devem ter evidências correspondentes. Após a importação, o plano não é mais atualizado.

Compilar ou Verificar Livro-Razão

Lê completamente references/runbook-schema.md.

Quando goal-runbook.md não existe:

1. Lê do plano os números, nomes, dependências e localizações dos contratos dos Gates.
2. Escreve a linha de base do código-fonte, o Livro-Razão Goal único e o Log de Progresso de cada Gate.
3. Sem estado importável, marca apenas G0 como active e os demais como planned.
4. Não copia Objetivo, Restrições, Verificação ou outros contratos de Gate do plano.

Quando goal-runbook.md já existe:

1. Compara o conjunto de caminhos de código-fonte e SHA-256; se houver desvio no plano ou nas decisões, mantém o livro-razão inalterado e para.
2. Verifica a ordem dos Gates, referências ao plano, dependências estritamente lineares, máquina de estados e evidências do Log de Progresso.
3. O livro-razão pode apresentar apenas passed* active planned*, passed* blocked planned* ou passed+.

O plano é a única fonte dos contratos; o livro-razão é a única fonte de estado e evidências. Nenhum dos dois pode copiar campos do outro ou gravar estado em duplicidade.

Escrever Prompt Fixo

Lê completamente references/goal-prompt-template.md, substitui apenas {{EFFORT_PATH}}, e escreve ou substitui goal-prompt.md.

O prompt fixo deve:

• Ser exatamente o mesmo em todos os Gates do mesmo esforço;
• Não conter Gates específicos (G0/G1), nomes de Gate ou Objetivo;
• Não expandir Entradas, Restrições, Verificação, Condições de Parada, Rollback ou Condições de Saída;
• Preservar o ciclo de execução estável entre projetos e restrições de comportamento: fatia mínima, controle de escopo, ciclo de fechamento em caso de falha de verificação, divisão de responsabilidades, preservação de implementações não relacionadas, não enfraquecimento de testes, transição de aceitação manual com encerramento e proibição de push;
• Exigir que, ao iniciar um Goal, o único Gate active seja bloqueado e apenas ele executado; na aceitação manual, solicitar confirmação uma única vez, registrar a evidência de transição, usar o estado final bem-sucedido fornecido pelo agente host para encerrar o Goal atual (não marcá-lo como blocked, paused ou continuar a execução), e então gerar uma saída de transição contendo o Gate, resultado da automação, ponto de entrada de aceitação, checklist mínimo, formato de resposta explícito e a mensagem "Goal encerrado, Gate ainda active", encerrando a sessão normal. Neste ponto, o Gate deve permanecer active; posteriormente, apenas o usuário pode reacionar manualmente um novo Goal com resultados de aceitação explícitos; se não houver mecanismo de estado do Goal, encerrar a tarefa atual imediatamente, sem criar um loop de espera. Quando um Gate passa, marcar o Gate atual como passed, o sucessor direto como active, resumir as evidências e encerrar explicitamente todo o Goal; não incluir o Gate sucessor no mesmo Goal.

goal-prompt.md é um arquivo de conveniência removível e recriável. Não faz parte da linha de base do código-fonte, não é referenciado pelo plano ou runbook e não participa da validação de estado.

A resposta final informa se houve compilação ou verificação, fornece os caminhos do plano, runbook e prompt fixo, e exibe o conteúdo do prompt. Ao otimizar artefatos, não implementa Gates.