Art4/continuous-refactoring

Varredura de Refatoração

Detecte, nunca escreva. Propõe o que pode ser trabalhado a seguir e percebe o que já foi resolvido desde a última passagem — nunca cria uma issue, nunca decide um resultado. refactor-design cria issues para o que for escolhido; refactor-learn age sobre o que esta skill detecta.

Processo

1. Verificar pré-condições

• Nenhum repositório git → interrompa a passagem, reporte-a, não proponha nada.
• Cinco ou mais issues abertas refactor:candidate → interrompa, não proponha nada novo; deixe o trabalho existente ser concluído primeiro.

2. Retomar trabalho pendente primeiro

Leia o campo Pending candidates do arquivo bookkeeping.md das Notas de Refatoração (skills/continuous-refactoring/references/refactoring-bookkeeping.md). Se nomear uma issue, uma passagem anterior do refactor-design a criou, mas foi interrompida antes de um merge request ser feito. Proponha exatamente essa issue e pare — terminar o trabalho pendente vem antes de propor trabalho novo.

3. Detectar estado lembrado fechado/unificado

Obtenha o conjunto lembrado — docs/agents/issue-tracker.md nomeia um rastreador de label nativo (GitHub, GitLab) → toda issue refactor:candidate aberta, cada uma resolvida para seu pull request vinculado via a referência cruzada nativa issue↔PR de fechamento do próprio rastreador (o Closes #<n> que o passo 5 do refactor-implement já coloca em um MR de entrega); uma issue sem PR vinculado ainda não tem nada a reconciliar nesta etapa. Caso contrário → toda entrada no merge-requests.md das Notas de Refatoração. Para cada uma, verifique o rastreador externo/git: o MR ainda está aberto? a issue ainda está aberta?

Nenhum gh/glab (ou outra API/token de forja) disponível → recorra à reconciliação apenas via git em vez de pular esta etapa (nunca tente instalar gh/glab aqui também — trate sua ausência exatamente como o gatilho deste fallback): skills/refactor-scan/references/git-only-reconciliation.md. Nenhum remote (git remote -v vazio) → a variante local-only do mesmo arquivo — um candidato lembrado pode ter sido unificado ou rejeitado por um humano trabalhando puramente localmente, conforme opening-a-merge-request.md's "Nenhuma forja/remote disponível".

• Unificado → uma constatação: entregue.

• Fechado sem unificação → uma constatação: recusado — anote se os comentários de fechamento fornecem uma razão estrutural do mantenedor (material fora do escopo) ou não.

• Ainda aberto, com atividade de revisor (uma revisão ou comentário) mais recente que o último commit do branch → um candidato a retomada, não uma constatação — ninguém decidiu nada ainda, só precisa de outra olhada. Acesso à API disponível → também leia o estado real da revisão junto com o timestamp (gh pr view <n> --json reviews,reviewDecision ou equivalente) — não pare em "algo mudou":

  • CHANGES_REQUESTED, não endereçado (nenhum commit mais novo que a revisão) → ainda um candidato a retomada, mas repasse os comentários/corpo da revisão junto com ele, não apenas o branch — o passo 1 do refactor-implement lê e aborda esse feedback específico, não apenas reexamina o branch do zero.
  • Um comentário, ou uma revisão APPROVED sem feedback bloqueador → o tratamento genérico existente de candidato a retomada; nada mais a anexar.

  Repasse-o da mesma forma que o passo 2 repassa uma entrada Pending candidates: diretamente para refactor-implement, pulando refactor-prioritize/refactor-design (já tem um design e um MR aberto; apenas o loop de correção se aplica — o passo 1 do refactor-implement já suporta retomar um branch existente). Sem acesso à API (fallback apenas git) → o estado da revisão permanece indisponível exatamente como git-only-reconciliation.md já documenta; este refinamento não se aplica lá.

• Ainda aberto, nada mudou → nenhuma constatação.

Verifique também toda entrada no out-of-scope/<node>.md das Notas de Refatoração que nomeia uma condição **Blocked by:** PHP >= X.Y (tooling_tree.py's detect_nodes() reporta isso diretamente quando executado; manualmente, compare com o require.php/config.platform.php do composer.json atual do alvo) — se a versão atual do PHP do alvo agora a satisfaz, uma constatação: esta rejeição é revertida. Nenhum campo Blocked by:, ou condição ainda não atendida → nunca uma constatação.

Repasse cada constatação para refactor-learn — esta skill apenas percebe; nunca marca nada como done/wontfix e nunca escreve no out-of-scope/ das Notas de Refatoração ela mesma.

3b. Detectar candidatos rotulados externamente

Acesso à API disponível (não o fallback apenas git) → também consulte issues abertas refactor:candidate que ainda não foram consideradas: nem a entrada Pending candidates do passo 2, nem o conjunto lembrado do passo 3 (uma issue com um pull request vinculado já está em andamento). O que sobra é um candidato que um humano (ou outro processo) rotulou diretamente, que este ciclo nunca projetou ou implementou — na operação normal, os candidatos do próprio conjunto são sempre cobertos por um desses dois, então nada extra é necessário para distinguir "nosso" do "de outro". Repasse cada um como uma proposta, a mesma lista à qual as propostas da árvore de ferramentas do passo 4 se juntam — refactor-prioritize as classifica junto com todo o resto em seus fatores usuais; elas competem por mérito próprio, nunca pulam a fila só por existirem. Sem acesso à API (fallback apenas git) → pule esta etapa inteiramente, git sozinho não pode enumerar issues por label.

4. Propor nós da árvore de ferramentas

Pule se o passo 2 já propôs um candidato pendente.

Execute python3 skills/refactor-scan/references/tooling_tree.py <target-repo> e leia o campo next do JSON — o conjunto real, atualmente desbloqueado, nós rejeitados (uma entrada existente no out-of-scope/<node>.md das Notas de Refatoração) já excluídos, aceite quantas entradas tiver. Não roadmap (uma simulação futura, não opções reais hoje). Leia também withheld: nós que estariam em next mas aguardam um pai recomendado não decidido — cada entrada nomeia qual(is) pai(is). Sem python3, ou não permitido → despache um subagente com o prompt de skills/refactor-scan/references/tree-walk-prompt.md ({N}=all) — ele percorre a mesma árvore de documentos manualmente (lê primeiro o campo Fulfilled nodes do bookkeeping.md das Notas de Refatoração para pular a rederivação de estado em cache, pula qualquer nó com uma entrada out-of-scope); sem mecanismo de subagente → execute seus passos você mesmo inline.

• Nós de ferramentas comuns (loop-config, e nós de especialização de linguagem, ex. skills/refactor-scan/references/php-tooling-tree.md) — propostos pelo seu Nome (nunca o slug bruto); cada um já está totalmente especificado em seu documento de árvore.
• structural-scan — proposto assim que todo nó com uma aresta resolved para ele é resolvido (cumprido, ou explicitamente rejeitado sob o out-of-scope/ das Notas de Refatoração): editorconfig na raiz genérica, mais o próprio nó de agregação da especialização de linguagem ativa (PHP: php-structural-scan), ele mesmo resolvido assim que cada um de seus próprios pais resolvidos é resolvido (skills/refactor-scan/references/tooling-tree.md). Apenas structural-scan é proposto desta forma — php-structural-scan é pura tubulação, nunca um candidato. Propô-lo é apenas nomeá-lo; a varredura da base de código acontece em refactor-design, apenas para o nó realmente escolhido.
• Nenhuma árvore de linguagem reconhecida: structural-scan ainda aguarda editorconfig, a folha raiz genérica — não imediatamente proponível só porque nenhuma árvore específica de linguagem se aplica.

Saída

Repassada adiante pelo orquestrador, claramente:

• Qual pré-condição interrompeu a passagem, se alguma — nada abaixo se aplica a esta passagem.
• Constatações (possivelmente vazias) → refactor-learn.
• Um candidato a retomada, se um foi detectado → diretamente para refactor-implement, ignorando refactor-prioritize/refactor-design.
• Propostas — apenas o candidato pendente, ou todo Nome de nó atualmente desbloqueado (nunca slugs, nunca limitado) mais qualquer candidato rotulado externamente do passo 3b, ou nenhum → refactor-prioritize. Todo nó atualmente desbloqueado (pais necessários cumpridos, não rejeitado, todo pai recomendado já decidido) — nunca um subconjunto truncado por prioridade. Junto com ele, nomeie todo nó withheld e qual(is) pai(is) ele está aguardando (ex.: "Rector: Type Coverage Set — aguardando: PHP CS Fixer").

Critério de conclusão

Constatações (se houver) repassadas para refactor-learn, um candidato a retomada (se houver) repassado diretamente para refactor-implement, propostas (se houver) repassadas para refactor-prioritize — ou uma pré-condição interrompeu a passagem e o relatório diz qual. Nunca um nó junto com entradas além de structural-scan na mesma lista.