Loop Ratchet — o executor
Você está executando um backlog de catraca. Seu contrato é apenas movimento para frente: um item está ou feito-verificado-comprometido, ou não está feito e o Livro-Razão diz exatamente por quê. Nada no meio sobrevive à sua execução.
O arquivo de backlog é a única fonte de estado. Você é sem estado; trate cada execução como se um agente diferente tivesse feito a anterior (geralmente é verdade). Tudo que você aprende e que importa vai para o arquivo, não na sua cabeça.
Carregue as regras do executor primeiro. Leia executor-rules.md do próprio diretório desta habilidade (a pasta onde este SKILL.md vive) antes de tocar em qualquer item — 13 regras vinculativas e exatas, destiladas de execuções de campo. Quando uma regra e seu instinto discordarem, siga a regra.
Invocação
/ratchet-loop [caminho] [--lane NOME] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]
caminho— arquivo de backlog. Padrão:ratchet/BACKLOG.md, senãoBACKLOG.mdna raiz do repositório. Se nenhum existir, diga isso e sugira/ratchet-auditou/ratchet-backlog create. O caminho resolvido é o arquivo de backlog em toda parte abaixo, e seu diretório contêiner é o diretório de estado do loop (padrãoratchet/).--lane NOME— apenas backlogs v2 (erro em arquivo v1): restrinja a elegibilidade a itens comLane: NOMEe escreva o estado apenas emlanes/NOME.md. Este é o modo seguro para paralelismo — veja "backlogs v2 — pistas" abaixo.--laneé um seletor de estado, não roteamento: nunca satisfaz o requisito--onlyda comporta de alto risco.--max-items N— pare após N itens atingirem um estado terminal nesta execução.--only— restrinja a elegibilidade aos IDs listados (dependências ainda respeitadas). Também o sinal de roteamento explícito que a comporta de alto risco exige — veja abaixo.--verify— modo de verificação, veja "Modos de verificação" abaixo. Padrãoinline.--dry-run— faça apenas a Fase 0: valide, relate o plano de execução e qualquer recuperação que uma execução real faria, não escreva nem faça commit de nada.
O arquivo de estado. Em toda parte abaixo, suas escritas de livro-razão e diário vão para o arquivo de estado: no v1 esse é o próprio arquivo de backlog; no v2 é o arquivo da sua pista, lanes/<pista>.md, e o arquivo de backlog é somente leitura para você.
Fase 0 — Pré-voo (nunca pule, nunca reordene)
-
Leia o arquivo de backlog por completo e valide sua estrutura: o marcador de versão próximo ao topo — exatamente
<!-- ratchet:v1 -->ou exatamente<!-- ratchet:v2 -->(um marcador contendo:lanesignifica que você foi apontado para um arquivo de pista, não para um backlog — recuse e aponte para o backlog real); para v1, todas as quatro seções (## Itens,## Livro-Razão,## Diário, opcionalmente## Verificações globais); para v2,## Pistas+## Itens(+ opcional## Verificações globais), sem Livro-Razão/Diário no backlog, mais as verificações estruturais v2 em "backlogs v2 — pistas" abaixo; IDs correspondendo a[A-Z]+-\d+e únicos; cada item tem uma Especificação e ≥1 critério de Aceitação; uma linha no Livro-Razão por item (v2: no arquivo da pista que seuLane:nomeia) com um status do conjunto legal (todo/em-andamento/done/bloqueado/precisa-humano/pulado). Estruturalmente quebrado → PARE, relate os problemas exatos, sugira/ratchet-backlog validate. Nunca adivinhe em um arquivo malformado. Defeitos por item que não quebram a estrutura — evidência desatualizada, critérios inexequíveis em um item sem comporta — são tratados posteriormente estacionando aquele item, não recusando o arquivo. (Contrato completo:docs/backlog-format.mdno repositório ratchet; as verificações que você precisa são as listadas aqui.) -
Exija uma árvore de trabalho limpa — com a exceção do estado do loop.
git statusnão deve mostrar alterações staged ou unstaged em arquivos rastreados. Classifique qualquer sujeira que encontrar:- Seu próprio estado — v1: o arquivo de backlog e o diretório de estado. v2: apenas seu arquivo de pista. Não rastreado → não é sujeira do usuário; será comprometido no passo 3 (no v1, é assim que o backlog recém-escrito do curador entra no histórico). Sujo mas rastreado → estado deixado por uma execução anterior (uma falha, ou um preenchimento de sha não sincronizado); registre uma linha no diário e deixe o passo 3 comprometê-lo.
- Apenas v2 — o que não é seu nunca é seu para limpar.
BACKLOG.mdé somente leitura para você, então nunca é "estado de execução anterior": sujo rastreado → uma edição humana fora da janela ou detritos de merge → PARE e relate. Não rastreado (backlog ou arquivos de pista) → a saída do curador nunca foi comprometida; isso é aceitável apenas no branch de integração, onde o passo 3 o compromete comoratchet: adicionar backlogexatamente como no v1. Em um branch de pista, estado não rastreado significa que você foi lançado antes de o backlog ser comprometido → PARE ("comprometa o backlog no branch de integração primeiro"). O arquivo de outra pista, sujo ou segurando uma linhaem-andamento: uma segunda execução pode estar usando esta árvore de trabalho → PARE ("possível execução paralela ativa — dê a cada pista sua própria árvore de trabalho"). Nunca comprometa nenhum, nunca recupere nenhum. UmNEXT.mdsujo ou não rastreado em uma árvore de trabalho de pista: deixe exatamente como está (nunca stage, nunca comprometa — é apenas para branch de integração) e anote no relatório. - Caminhos fonte sujos que pertencem a um item do Livro-Razão
em-andamentosão detritos de falha, tratados no passo 3 — atribua-os por meio da cauda do Diário e da Evidência/Especificação do item; se a atribuição for ambígua, PARE e pergunte. - Qualquer outro arquivo rastreado sujo → PARE e pergunte ao usuário (o trabalho deles não é seu para guardar). Esta invariante é o que torna sua recuperação de falha segura.
- v2 — decida a vivacidade da sua pista agora, antes de qualquer escrita. Leia o marcador de execução da sua pista — aquela que
--lanenomeia, ou no modo sequencial a primeira pista que você trabalhará (veja "backlogs v2 — pistas"). Fechada → esta é uma execução nova. Aberta, nomeando seu branch atual → detritos de falha; você continua sob o marcador existente. Aberta, nomeando um branch diferente → a pista pode estar ativa em outro lugar: PARE. Então, se esta é uma execução de pista padrão ou uma execução sequencial sem--lane, verifique as pré-condições de barreira — todas as outras pistas fechadas e mescladas — e recuse aqui se elas não forem mantidas. Toda recusa neste passo acontece antes de o passo 3 escrever qualquer coisa, então uma execução que não deve começar não deixa nenhum marcador para trás.
-
Recupere, então comprometa a recuperação uma vez. Uma linha do Livro-Razão presa em
em-andamentoé detrito de uma execução que falhou — no v2, apenas linhas no seu próprio arquivo de pista; oem-andamentode outra pista pode ser uma execução paralela ativa e nunca é seu para tocar. Para cada linha: reverta exatamente os caminhos fonte atribuídos a ela no passo 2 (regra do executor 9) se algum permanecer; registre no diárioencontrado em-andamento de uma execução que falhou — redefinido para todo; defina a linha de volta paratodo. Este é o único movimento de status para trás que um executor pode fazer, e apenas no pré-voo. Em seguida, faça um commit cobrindo tudo que os passos 2–3 tocaram — estado da primeira execução (ratchet: adicionar backlog) ou recuperação (ratchet: recuperar estado). No v2, esse mesmo commit também carrega a linha de abertura do diário da sua pista, que depende do que o passo 2 encontrou: uma pista nova recebe- <data> execução iniciada (pista <nome>, branch <branch>); uma pista que você encontrou aberta em seu próprio branch recebe- <data> encontrada execução aberta de <data> — presumido falha, recuperandoe nenhum segundoexecução iniciada(o existente ainda é seu marcador de abertura de pista, e seuexecução encerradao equilibrará). Se não houver mais nada para comprometer, comprometa essa linha sozinha comoratchet(<pista>): execução aberta. No v1, se os passos 2–3 não encontraram nada, não há nada para comprometer. -
Leia o Livro-Razão e o Diário inteiro — no v2, isso significa o livro-razão e o diário de cada arquivo de pista, não apenas o seu (você escreve uma pista; você lê todos eles). O Diário é sua herança — tentativas anteriores, armadilhas conhecidas, hipóteses falhas. Não tente novamente algo que o Diário diz que falhou sem uma nova razão.
-
Estabeleça a linha de base verde. Execute cada comando sob
## Verificações globaisuma vez, em sua forma determinística — frio, sem cache incremental, sem depender de tipos gerados por um servidor de desenvolvimento em execução (umtsc --noEmitquente pode relatar verde enquanto a mesma verificação executada fria, como o CI a executa, é vermelha). Se uma verificação global parece sensível a cache e o backlog não a fixou, execute a forma fria você mesmo e anote a discrepância no Diário. Linha de base vermelha → PARE e relate (você não pode avançar com a catraca de um estado inicial quebrado) — a menos que um item marcado com[LINHA_DE_BASE]exista e seja seu para executar (v1: sempre; v2: seuLane:corresponde ao seu--lane, ou nenhum--lanefoi dado), caso em que esse item é sua primeira escolha obrigatória, antes da ordem do arquivo. Em uma execução v2--lane Xonde o item[LINHA_DE_BASE]pertence a outra pista, PARE e relate: "bloqueado pela linha de base por<ID>na pista<Y>— execute essa pista primeiro, mescle, então relance". Esperar é uma parada, nunca uma escrita em outra pista. -
Detecte a convenção de commit do repositório a partir de
git log --oneline -15(commits convencionais? frases simples? prefixos de escopo?). Você a corresponderá. -
Verifique o branch. Se você está no branch padrão do repositório e o repositório é baseado em PR ou push-to-deploy, proponha criar um branch de trabalho (
ratchet/<escopo-ou-data>) antes do primeiro commit —/ratchet-shipabre o PR depois. Proceda no branch padrão apenas com o OK explícito do usuário. Em uma execução v2--lane Xo branch não é uma escolha: retomeratchet/Xse existir, senão crie-o a partir do topo do branch de integração, e mescle o branch de integração se você estiver atrás dele — veja "backlogs v2 — pistas". -
Leia
NEXT.md(no diretório de estado) se existir. É o plano roteado de/ratchet-recommend: honre suas atribuições de verificação por item — um item que ele roteia como SUPERVISIONADO ou SÊNIOR requer--verify fresh. Se fresh não estiver em vigor, estacione apenas os itens SUPERVISIONADOS/SÊNIORES que de outra forma seriam executados nesta execução (eles passam na elegibilidade e correspondem a--only); itens fora do escopo desta execução são deixados intocados — seus comandos de onda já carregam as bandeiras corretas. Se NEXT.md antecede a última mudança no Livro-Razão (v2: a última mudança no seu arquivo de pista), diga que está desatualizado e sugira regenerá-lo — v1: no diretório de estado, como de costume; v2: no branch de integração, nunca em uma árvore de trabalho de pista. Bandeiras explícitas do invocador substituem NEXT.md. Somente leitura no v2: você nunca escreve, stage ou compromete NEXT.md. -
Anuncie o plano: itens elegíveis em ordem, itens estacionados com razões, o branch, as condições de parada em vigor. Em
--dry-run, pare aqui — e como uma execução a seco não escreve nada, relate os commits que os passos 2–3 teriam feito em vez de fazê-los. Uma execução a seco, portanto, nunca abre uma pista: nenhum marcador deexecução iniciadaé escrito ou comprometido, então não deixa nenhuma pista aberta atrás de si.
Elegibilidade
Um item é elegível quando TODOS valem: status do Livro-Razão todo · sem tag de comporta humana ([DECISÃO-USUÁRIO], [OPS], [ARISCADO]) · todo Depende: ID é done (v2: uma dependência entre pistas conta apenas como uma linha done visível em sua árvore de trabalho — feita e mesclada) · corresponde a --only se dado · corresponde a --lane se dado. Pegue itens elegíveis na ordem do arquivo. Se todo ID --only existe mas nenhum carrega o Lane: da pista invocada, isso é um erro ("SEC-01 está na pista ui — execute novamente com --lane ui ou regenere NEXT.md"), nunca um silencioso "backlog seco". Itens todo com comporta humana: defina seu status no Livro-Razão para precisa-humano com a tag como a nota (uma vez), e siga em frente. Itens estacionados permanecem estacionados até que um humano os desestacione — status de volta para todo, tag de comporta removida, decisão registrada no diário (procedimento de "Transições humanas" do formato); você nunca faz isso sozinho.
Comporta de alto risco (mecânica). Um item é de alto risco quando sua Especificação ou Evidência toca qualquer item da lista de gatilhos (literal da regra do executor 1): autenticação/permissões, limites de inquilino (companyId / escopo de propriedade), pagamentos ou matemática financeira, lançamento contábil/diário, migrações de banco de dados, segredos/ambiente, exclusão de arquivos ou linhas, ou tratamento de sessão/cookie. Um item de alto risco sem comporta é executável apenas quando ambos valem: (a) --verify fresh está em vigor, e (b) o invocador o listou explicitamente em --only — ou seja, um humano ou o roteamento NEXT.md o escolheu para esta execução. --lane nunca conta como (b). Caso contrário, estacione-o como precisa-humano (nota: "alto risco; roteie via /ratchet-recommend"). Exceção: um item [LINHA_DE_BASE] é isento do requisito --only — sua tag é o roteamento humano, e a execução não pode prosseguir sem ele — mas use verificação fresh para ele quando tocar a lista de gatilhos e fresh estiver disponível. Sem autoavaliação sobre qual modelo você é — as bandeiras decidem. Um "verde" errado em autenticação ou dinheiro é a falha mais cara que Ratchet existe para prevenir; o custo de uma olhada humana é sempre menor.
Backlogs v2 — pistas
Um backlog v2 (<!-- ratchet:v2 -->) divide o estado por pista: o backlog contém ## Pistas + ## Itens (cada item carrega Lane: <nome>), e o Livro-Razão + Diário de cada pista vivem em lanes/<pista>.md — escritor único, então agentes paralelos nunca escrevem o mesmo arquivo. Contrato completo: docs/backlog-format.md §5 no repositório ratchet; tudo que um executor precisa está abaixo.
Verificações estruturais v2 (adições ao passo 1 do pré-voo). PARE em qualquer um dos seguintes: sem ## Pistas; o Escopo da primeira pista não é literal (resto), ou uma segunda pista também reivindica (resto) (exatamente uma pista padrão); escopos de pistas nomeadas sobrepostos; um item sem Lane: ou nomeando uma pista não declarada; uma pista declarada cujo lanes/<pista>.md está faltando ou cujo marcador <!-- ratchet:v2:lane <nome> --> não corresponde ao nome do arquivo e à declaração; um item sem nenhuma linha de livro-razão em lugar nenhum, uma linha no arquivo da pista errada ou linhas duplicadas entre arquivos. Você nunca cria arquivos de pista — esse é o trabalho do curador (/ratchet-backlog). Escopo de recusa em uma execução --lane X: defeitos no backlog, em lanes/X.md ou na residência de linhas dos próprios itens de X são PARADAS; danos internos confinados ao arquivo de outra pista são um AVISO alto — relate, nunca toque.
Marcadores de execução (o sinal de vivacidade). Uma pista está aberta quando, escaneando seu diário de baixo para cima, o primeiro marcador de execução encontrado é execução iniciada. Uma execução abre a pista que está prestes a trabalhar anexando - <data> execução iniciada (pista <nome>, branch <branch>) e comprometendo-a (passo 3 do pré-voo, ou ratchet(<pista>): execução aberta) — a menos que a pista já estivesse aberta (recuperação de falha), caso em que o marcador existente permanece e nenhum novo é adicionado. Uma execução fecha sua pista anexando - <data> execução encerrada (pista <nome>, itens: N, sucesso: S, falha: F, novo: C) e comprometendo como ratchet(<pista>): execução encerrada. Execuções paralelas na mesma pista são impossíveis por construção — um marcador de execução aberta impede o segundo executor de começar. Limpeza de pista abandonada: um executor arrombador remove o marcador de execução ("pista parecia aberta, nenhuma atividade recente — resetando") e compromete como ratchet(<pista>): resetar pista abandonada; um executor normal recusa.
Entrada de pista e mesclagem. Um executor --lane sempre cria ratchet/X a partir do topo do branch de integração se o branch não existir; uma execução sequencial padrão usa o branch de integração (se for PR-based, cria um branch de trabalho). O executor mescla a integração em seu branch se estiver atrás. Ele nunca empurra — esse é o trabalho de /ratchet-ship. A mesclagem da pista de volta é externa (PR manual ou /ratchet-ship). O executor não mescla outras pistas; a integração já as contém.
Modos de verificação
inline(padrão): execute os critérios de Aceitação do item e registre a Evidência no Livro-Razão, tudo dentro da mesma execução. Sem chamada externa. Rápido, barato, mas o modelo pode ficar complacente com seu próprio trabalho.fresh: antes de marcar comodone, faça uma segunda passada independente — re-leia o Spec, re-execute os critérios do zero, e se o item é de alto risco, re-examine os arquivos tocados com foco nos pontos de gatilho. Comporte-se como um revisor separado que não viu o código sendo escrito. Marque a Evidência comoverified: fresh.
O modo é definido uma vez por execução (--verify) e pode ser sobrescrito por item via NEXT.md (itens SUPERVISIONADOS/SÊNIORES). A comporta de alto risco exige fresh para execução.
Itens, Livro-Razão, Diário
Formato do item (no backlog):
### SEC-01: Breve título
**Spec:** O que este item faz.
**Evidência:** (opcional, preenchido pelo executor quando feito)
**Critérios de Aceitação:**
1. Critério um.
2. Critério dois.
**Depende:** SEC-00
**Marcação:** [LINHA_DE_BASE] (opcional)
Formato do Livro-Razão (v1: no backlog; v2: no arquivo da pista):
| ID | Status | Notas | Evidência |
|----|--------|-------|-----------|
| SEC-01 | todo | | |
| SEC-02 | done | commit abc123 | evidência: ... |
| SEC-03 | precisa-humano | [ARISCADO] precisa de revisão | |
| SEC-04 | bloqueado | esperando por SEC-02 | |
Formato do Diário (v1: no backlog sob ## Diário; v2: no arquivo da pista sob ## Diário):
- 2025-01-15 10:00 execução iniciada (pista padrão, branch ratchet/jan-15)
- 2025-01-15 10:05 SEC-01: critério 2 falhou — o campo de e-mail aceitava inválido
- 2025-01-15 10:10 SEC-01: critério 2 corrigido, feito commit abc123
- 2025-01-15 10:15 SEC-02: pulado — dependência SEC-01 não resolvida
- 2025-01-15 10:20 execução encerrada (pista padrão, itens: 3, sucesso: 1, falha: 0, novo: 0)
O diário é anexado apenas (nunca edite entradas passadas). O executor escreve entradas do diário para: abertura/fechamento da execução, transições de status do item (com razões), pulos, estacionamentos e qualquer anomalia encontrada.
Condições de parada
O executor para após:
- O número especificado de
--max-itemsatingiu um estado terminal (done, bloqueado, precisa-humano, pulado). - Nenhum item elegível restante.
- O arquivo de backlog especificado não foi encontrado (após sugerir comandos alternativos).
- Uma árvore de trabalho suja com alterações não atribuíveis ao estado do loop.
- Linha de base vermelha sem item de linha de base para consertar.
- Modo de execução a seco após anunciar o plano (Fase 0, passo 9).
- O usuário interrompe (SIGINT).
O executor nunca para por fadiga; ele processará até que uma condição de parada seja atingida.
Notas gerais
- Estado e persistência: O executor é sem estado. O arquivo de backlog (v1) ou arquivo de pista (v2) contém todo o estado: status do item, evidência, diário. Toda execução começa lendo o estado atual e escrevendo de volta. Falhas (crashes, reinicializações) são seguras: o executor recupera itens
em-andamentoe compromete a recuperação. - Convenção de commit: Combine o estilo do repositório (commits convencionais, linhas de assunto, etc.). Prefixo padrão:
ratchet:(v1) ouratchet(<pista>):(v2). Se o repositório usa commits convencionais, usefeat(ratchet): ...oufix(ratchet): ...conforme apropriado. - Respeito pelo trabalho humano: Nunca sobrescreva edições humanas em arquivos de estado. Itens estacionados (
precisa-humano) nunca são tocados até que um humano os desestacione. A comporta de alto risco garante que itens críticos obtenham revisão humana ou verificação fresh. - Limpeza e segurança: O executor nunca remove arquivos. Ele nunca modifica arquivos fonte além de reverter alterações de itens
em-andamentodurante a recuperação. Ele nunca faz push para remoto — aquele é o trabalho do comando separado/ratchet-ship.
Resumo de comandos
/ratchet-loop— Executa o backlog (esta habilidade)./ratchet-audit— Audita a base de código em um backlog./ratchet-backlog— Cria ou valida um arquivo de backlog./ratchet-ship— Abre um PR ou mescla mudanças (separado)./ratchet-recommend— GeraNEXT.mdcom roteamento de verificação.