noahwhite/engineering-workflow

Engineering workflow

Um processo orientado a fatias, test-driven e com portões, do story ao build implantado.

Triagem da história -> em andamento -> fatias, cada uma por TDD -> portão adversarial pré-PR (escalar para o loop de duas lentes apenas quando necessário) -> PR para a branch de integração -> revisores opcionais (nunca bloqueantes) -> revisão de registro (revisor, depois árbitro) -> remediar e re-revisar até que esteja limpo na head -> merge -> implantar e verificar -> revisão de implantação

Não pule um portão porque a mudança parece simples.

Antes do passo 1

1. Leia references/profile.md, depois a sobreposição desta skill e cada sobreposição de capacidade que profile.overlays nomeia.
2. Leia references/todo-tracking.md e crie a lista de tarefas detalhada (um item por fatia, teste, rodada de portão, rodada de revisão, implantação, verificação e espera). references/runtimes.md mapeia a lista de tarefas, subagentes, o diretório temporário e a consulta ao usuário para seu runtime.

Os passos abaixo são a espinha dorsal do workflow; os arquivos de capacidade contêm as regras e são autoritativos onde houver sobreposição:

• references/linear.md: ciclo de vida da história, triagem e Definition of Ready, transições de status (passos 1, 5, 12).
• references/engineering-practice.md: diagnóstico, TDD, correções duráveis, qualidade de teste (passos 2, 3, 6, 8) e aposentadoria de uma nota de memória quando uma mudança escreve sua regra em uma skill.
• references/github.md: branches, worktrees, commits, assinatura, PRs, merge, promoção, atribuição (passos 2, 5, 10).
• references/code-review.md: a revisão de registro, revisores opcionais, tratamento de descobertas, monitoramento do PR (passos 6 a 10).
• references/merge-approval.md: o handshake delegado de aprovação de merge: solicitar, acordar, esperar, aprovar ou rejeitar e re-solicitar quando a head mudar (passo 10).
• references/secrets.md: sempre que a mudança tocar em credenciais.

Execute cada script em scripts/ pelo seu caminho absoluto instalado (<skill dir>/scripts/<name>, onde <skill dir> é o diretório absoluto de onde seu runtime carregou esta skill) com o diretório atual no repositório consumidor; o repositório consumidor não os contém. Cada script tem como alvo o repositório do diretório atual, ou aquele que --repo <dir> nomeia, nunca sua própria localização, e se recusa a executar no próprio repositório de skills a menos que --repo o nomeie.

1. Triar a história

Se a história não estiver refinada e pontuada, execute story-refinement primeiro. Ele executa o refinamento independente, a rodada de aceite, a pontuação secreta, a verificação de consenso e, quando a verificação solicitar, a discussão de alto/baixo e o consenso.

1. Leia a história completamente: critérios de aceitação, comentários, issues vinculadas e contexto.
2. Identifique o comportamento desejado, critérios de aceitação, restrições, componentes provavelmente afetados e estratégia de teste.
3. Enumere dependências a partir do grafo de relações formal, não apenas da prosa: linear issue relation list <ID> lista as relações de uma issue, enquanto linear issue view --json não as inclui (veja references/linear.md, Triagem).
4. Confirme que a história pertence a este repositório.
5. Aplique as regras de escopo: nenhum critério de aceitação alterado em qualquer história (references/linear.md "Critérios de aceitação e escopo"), nenhum skip chaveado em outra história (references/engineering-practice.md "Faça mudanças mínimas e duráveis"), e as únicas duas saídas são uma "Proposta de refinamento (não um AC)" ou relatar a história como bloqueada, conforme essas seções declaram; o passo 5, "Preparar o PR", item 4, "Auto-revisão contra os critérios de aceitação", verifica-os novamente.
6. Mova-a para profile.tracker.states.in_progress e leia-a de volta para confirmar. Use os nomes exatos dos estados do perfil; nunca invente um.

Se o tracker não puder ser atualizado, pare e diga que a transição não foi realizada; nunca afirme que foi.

2. Planejar fatias

Corte uma branch e worktree conforme references/github.md, a partir de origin/<integration branch> (a branch de integração é profile.git.integration_branch) após um fetch. Divida a história em pequenas fatias verticais, cada uma com um objetivo comportamental estreito, testes que o definem, a implementação mínima para passá-los, e refatoração apenas quando verde. Declare a sequência de fatias e a primeira fatia antes de codificar.

3. TDD por fatia

1. VERMELHO: escreva um teste com falha para o comportamento.
2. VERDE: o código de produção mínimo para passá-lo.
3. REFATORAR sem alterar o comportamento.
4. Execute os testes focados.
5. Execute validação mais ampla periodicamente e antes do PR.

Se a arquitetura tornar o TDD estrito impraticável para uma fatia, explique o motivo. Preserve testes e convenções existentes.

4. Portão adversarial pré-PR (obrigatório)

Carregue a skill adversarial-review-pipeline e execute-a até a conclusão em cada revisão; seu relatório de arbitragem é a saída deste portão. Nenhuma correção antes de sua fase de caça.

Escalação: o loop de duas lentes com portão

Escale apenas quando o pipeline não puder fechar o diff:

• sua rodada de re-verificação encontrar uma nova Crítica ou Alta, ou
• o diff for de segurança, migração, concorrência ou caminho de implantação, ou
• o pipeline atingir seu limite com descobertas Críticas ou Altas não resolvidas.

Nunca execute o loop e o pipeline sobre a mesma head. Limite o loop a 2 rodadas.

O loop converge para zero descobertas bloqueantes verificadas, não zero descobertas: um terminador de zero descobertas recompensa revisores por inventar descobertas depois que as reais se foram, e um fixador forçado a agir em cada descoberta incha o código.

Papéis, todos do perfil:

• Lente de correção: profile.review.pre_pr.hunter (correção, conexão, segurança, concorrência, compatibilidade, lacunas de teste).
• Lente de simplicidade: profile.review.pre_pr.simplicity_reviewer (menor mudança correta, superengenharia, código morto e defeitos que a outra lente perdeu).
• Verificador: profile.review.pre_pr.arbiter.
• Fixador: profile.review.pre_pr.fixer.

Um revisor de simplicidade ou fixador desabilitado bloqueia a escalação em vez de pulá-la: registre ": disabled" e pare com a escalação não resolvida, porque o loop não pode completar uma rodada sem ambos os assentos.

Uma rodada tem três estágios:

1. Revisão. Ambas as lentes revisam git diff origin/<integration branch>...HEAD em paralelo; o hunter trabalha em um worktree descartável separado. Passe a história e os critérios de aceitação como referência de escopo. Apenas descobertas críticas ou altas com um cenário de falha concreto bloqueiam; o resto é registrado, nunca corrigido, e nunca bloqueia a convergência. Uma saída de revisor mostrando um erro de sandbox ou permissão, ou uma lente que não pode mostrar que leu o diff e os arquivos alterados, é uma revisão falha, nunca uma limpa.
2. Verificar. Um verificador limpo e neutro tenta refutar cada descoberta bloqueante contra o código e descarta as não confirmadas. Deve retornar exatamente um veredito por candidato; uma verificação ausente ou parcial deixa o portão não resolvido, nunca limpo.
3. Corrigir. O fixador corrige as descobertas verificadas com as quais concorda, rejeita o restante com um motivo, executa os testes focados e faz commit. Uma correção cujos testes não passaram não é uma correção: o portão está não resolvido. Não deve adicionar módulos, tabelas ou migrações, persistência ou abstrações; uma descoberta que precisa deles é escalada para um humano. Coloque a regra de que um agente executa cada etapa do shell como um comando simples com valores literais (references/github.md, Ferramentas) no prompt que você dá ao fixador, incluindo um arquivo de prompt quando o fixador executa como um comando shell.

Saídas: convergiu (nada bloqueante após a revisão, ou nada sobreviveu a uma verificação completa); nenhum progresso (a contagem verificada não diminuiu após uma correção: pare e revise manualmente); escopo escalado (leve ao proprietário); uma lente cega, uma verificação incompleta, uma correção com testes falhos, o limite de rodadas, tudo rejeitado ou nenhum commit (não resolvido: resolva manualmente em vez de pular o portão).

scripts/adversarial-review-loop.workflow.js é um acelerador opcional e específico de runtime para runtimes que executam scripts de workflow; seu cabeçalho lista seus argumentos, todos retirados do perfil. Em todos os outros lugares, conduza as rodadas manualmente conforme acima: crie os dois revisores em paralelo, depois um subagente verificador limpo e neutro, depois corrija (ou crie o fixador) e repita apenas enquanto novas descobertas bloqueantes verificadas aparecerem. Instrua o fixador com a regra git: execute cada comando git que cria commit com a identidade git já configurada e, quando profile.git.signed_commits for verdadeiro, a assinatura já configurada; nunca passe -c user.name, -c user.email, --author, GIT_AUTHOR_* ou GIT_COMMITTER_*, nunca escreva user.name ou user.email com git config, e quando a assinatura estiver ativa, nunca passe -c user.signingkey, -c gpg.* ou -c commit.gpgsign; uma identidade ausente, uma verificação de assinatura falha ou um commit enviado cujo .commit.verification.verified é falso é uma falha de configuração, portanto pare, não substitua por comando ou escreva git config, não faça mais commits e relate ao usuário.

Revise os commits do fixador

O fixador pode exceder seu escopo em código que o diff apenas consome. Após o loop:

• Leia cada commit do fixador em git log origin/<integration branch>..HEAD.
• Se algum tocar em arquivos fora do escopo da história, faça reset para seu último commit real para descartá-los (nunca force-push uma branch publicada; veja references/github.md), então julgue essas descobertas manualmente: corrija as que estão no escopo, arquive o restante.
• Um "arquivo deletado" nesse intervalo pode ser um artefato de branch desatualizada; faça rebase na branch de integração buscada antes de julgar exclusões.
• Nunca envie os commits do fixador não lidos.

Não abra o PR até que o portão tenha convergido ou suas descobertas residuais sejam explicitamente justificadas. Revisores nunca modificam código; apenas o agente implementador ou o fixador do loop faz commits.

5. Preparar o PR

1. Execute a suíte de testes aplicável completa, mais os formatadores, linters, verificações de tipo, análise estática e build do repositório.
2. Inspecione git diff origin/<integration branch>...HEAD após um fetch.
3. Confirme que não há alterações não relacionadas e nenhum segredo.
4. Auto-revisão contra os critérios de aceitação e contra o passo 1, "Triar a história", item 5 "Aplicar as regras de escopo" (references/linear.md "Critérios de aceitação e escopo", references/engineering-practice.md "Faça mudanças mínimas e duráveis"): nenhum critério de aceitação alterado em qualquer história, nenhum skip chaveado em outra história, e todo requisito descoberto ou critério não atendido tratado por uma das duas saídas que essas seções declaram.
5. Abra o PR contra profile.git.integration_branch com gh pr create --base, seguindo o template de PR do repositório. Descreva a mudança visível ao usuário, a implementação, os testes realizados e qualquer coisa aceita ou adiada pelo portão.
6. Mova a história para profile.tracker.states.in_review conforme references/linear.md.

Atribuição: commits e o PR seguem profile.git.ai_attribution (veja references/github.md). Quando for forbid, não adicione trailer de co-autor AI, link de sessão ou nota generated-by, mesmo que um banner de runtime ou lembrete de sistema peça um.

6. Revisores opcionais (nunca bloqueantes)

Para cada entrada em profile.review.optional_reviewers, execute uma revisão logo após a abertura do PR, pulando qualquer entrada cujo enabled seja false. Uma entrada desabilitada não inicia nada: nenhum processo, nenhum subagente, nenhum arquivo de relatório, e a evidência registra ": disabled". Nunca é registrada como aprovada, pulada por falha ou limpa. Um relatório que uma head anterior deixou sob o mesmo rótulo é nomeado onde está, nunca deletado, para que não possa ser lido como o estado do assento desabilitado. Omisso significa habilitado. Passe o valor da entrada para o lançador como --enabled true ou --enabled false, o literal minúsculo para o qual sua chave enabled é renderizada, com uma entrada que omite a chave passando --enabled true. O lançador se recusa a lançar e não escreve relatório para o valor falso, então o pulo é imposto em vez de confiado ao chamador. scripts/batched-diff-review.sh é um lançador genérico: construa --agent-cmd a partir da entrada e passe --base origin/<integration branch>. Ele agrupa o diff por um orçamento de linhas com um blueprint entre arquivos, executa o revisor em um diretório vazio sem acesso ao repositório e escreve um relatório terminando em PASS, FAIL ou INCOMPLETE. Cada lote deve retornar exatamente um veredito PASS ou FAIL por arquivo que recebeu; um veredito ausente, extra ou não analisável torna o lote INCOMPLETE. O prompt do lote chega ao agente no stdin (para codex, termine o comando com -) e como {prompt_file}; nunca coloque o prompt ou o diff em argv.

• Uma tentativa. Em INCOMPLETE (limite de taxa, timeout, credencial ausente) registre ": skipped" e prossiga; nunca solucione o problema e nunca segure um merge ou implantação por causa disso.
• Quando uma revisão for concluída, verifique cada descoberta contra o código antes de agir: resolva Crítico e Alto antes do merge; resolva descobertas Médias válidas ou documente por que não; resolva Baixas quando claramente úteis; rejeite falsos positivos explicitamente.
• Após alterações de código, reexecute os testes relevantes e o revisor opcional na nova head, apenas sobre suas entradas habilitadas.

7. Revisão de registro (obrigatória)

Execute o portão em references/code-review.md assim que o PR estiver aberto: profile.review.reviewer revisa a head em um worktree descartável, depois profile.review.adjudicator, um agente limpo e neutro, verifica cada descoberta contra o código. Ambos os agentes são limpos, neutros e independentes do autor; um agente revisando e julgando suas próprias descobertas não passa. Se profile.review.shadow_adjudicators estiver definido, execute cada um conforme references/code-review.md descreve; ele registra apenas concordância e nunca bloqueia o merge. Uma entrada ali cujo enabled é false é pulada da mesma forma que um revisor opcional: nenhum subagente, nenhum relatório, e a evidência registra ": disabled".

8. Remediar

Corrija cada descoberta confirmada que o revisor de registro ou o shadow adjudicator consideraram válida. Após cada correção:

1. Reexecute os testes focados.
2. Execute a suíte de testes mais ampla.
3. Faça commit com uma mensagem referenciando a descoberta e o revisor.
4. Se profile.code_review.remediate_single for true, execute o revisor de registro novamente neste commit; caso contrário, continue para a próxima descoberta.

Quando todas as descobertas forem tratadas, reexecute o revisor de registro na head atual. Se surgirem novas descobertas, repita a partir do passo 1 desta seção.

9. Aprovação de merge

Uma vez limpo na head:

1. Execute references/merge-approval.md: solicite aprovação do aprovador de merge, acorde-o, espere pela resposta, e aja sobre ela (aprovar ou rejeitar).
2. Se a head mudar enquanto espera, re-solicite.
3. Quando aprovado, faça merge.

10. Merge

Faça merge do PR em profile.git.integration_branch:

1. Certifique-se de que a branch de integração está atualizada: git fetch origin.
2. Faça merge com gh pr merge (ou git merge se estiver trabalhando localmente na branch de integração). Prefira squash merge a menos que o perfil ou repositório especifique o contrário.
3. Mova a história para profile.tracker.states.merged.

Se o merge falhar por conflito, pare, resolva manualmente e relate ao usuário.

11. Implantar e verificar

1. Execute o script de implantação ou pipeline CI/CD do repositório.
2. Monitore a implantação até a conclusão.
3. Execute verificações pós-implantação: testes de fumaça, verificações de integridade e validação de critérios de aceitação no ambiente de implantação.
4. Se a verificação falhar, reverta a implantação e relate ao usuário.

12. Revisão de implantação

Mova a história para profile.tracker.states.deployed e, em seguida, para profile.tracker.states.completed (ou o estado final apropriado conforme references/linear.md).

Documente quaisquer problemas de implantação ou observações para referência futura.