[🛠] Operations Automation #4: Uma estrutura que evita estados stale alterando menos documentos

✨ Resumo do GPT-5.6 Sol

Um registro da reorganização do fluxo de atualização da documentação, abandonando a cópia de cada mudança de estado entre vários documentos e adotando um único owner para o estado volátil, downstreams condicionais e checkpoints de phase.

Quanto mais documentos eu atualizava, mais o estado atual se dividia

Depois que um trabalho longo era compactado ou transferido para outra session, às vezes uma próxima tarefa registrada em um documento antigo era confundida com o estado atual. Para impedir esse problema, durante algum tempo eu corrigia todos os documentos que pareciam relacionados sempre que o estado mudava.

Eu repetia o mesmo fato concluído e a próxima tarefa no README, no router de documentos, nos requisitos, na direção atual, no Runbook e no TODO. Parecia seguro desde que nenhum documento fosse esquecido.

Mas, a partir do momento em que uma única mudança de estado era escrita em seis lugares, esses seis lugares precisavam continuar idênticos. Um documento ficava no estado anterior ao deploy, enquanto outro dizia que a verificação em dispositivo real já havia terminado. Atualizar muitos documentos, em vez de impedir estados stale, passou a criar novos estados stale.

Cada pequena verificação concluída também levava à edição de vários documentos e a mais um commit, fragmentando o Git history. Ficava mais fácil ver quantas vezes o texto havia sido sincronizado do que onde a implementação realmente terminava.

Dei a apenas um documento a propriedade do estado volátil

O problema não era a quantidade de documentos, mas vários documentos possuírem o mesmo fato. Por isso, primeiro defini um único owner para cada tipo de fato.

Fato alterado	owner	Condição para alterar outros documentos
Runtime atual, blocker, phase e próxima tarefa	canonical current-state snapshot	Não copiar para outros documentos
Decisões de produto estáveis, desvios proibidos e Goal ativo	Documento current-direction	Somente quando a própria decisão de produto ou o Goal mudar
Comportamento, dados, permissões e acceptance	requirements ou contract	Somente quando o contrato de comportamento do usuário ou do sistema mudar
Procedimento operacional, gate, rollback e recovery	Runbook	Somente quando o procedimento que o operador deve seguir mudar
Relações entre documentos, etapa do produto e ponto de entrada de execução	README ou router	Somente quando o caminho de navegação ou a relação do produto mudar
Comandos detalhados, logs e verificações de workers	report, artifact e Git evidence	Deixar apenas a conclusão e o link da evidência nos documentos aggregate

O essencial é separar estar relacionado de ser o owner. O fim de um deploy não exige alterar os requisitos. Se o procedimento operacional de rollback mudou durante o deploy, o Runbook é atualizado; se o contrato de comportamento também mudou, só então os requirements são atualizados.

O README e o router também deixaram de acompanhar revision atual, estado do dispositivo e próxima tarefa. Esses documentos apontam de forma estável apenas o que deve ser lido e de onde a execução deve começar.

Separei atualização imediata de durable checkpoint

Ter um único owner não significa adiar a atualização do documento até o fim da phase. Quando surgem novas evidências ou mudam o estado do Runtime, o blocker, a prioridade ou a próxima tarefa, o canonical current-state snapshot é corrigido antes da implementação seguinte. Assim, mesmo que o contexto seja compactado ou transferido no meio do trabalho, a próxima session pode recuperar o estado real em um único lugar.

Por outro lado, não se cria um commit a cada linha de estado alterada. O current-state é verificado uma vez e um checkpoint é criado apenas em uma fronteira que possa ser revisada e retomada de forma independente.

• quando a implementação termina
• quando o deploy e a verificação posterior terminam
• quando há um resultado de E2E em dispositivo real ou no ponto de entrada do usuário, ou quando um blocker é confirmado
• quando o trabalho é transferido por interruption ou handoff

A atualização imediata existe para tornar o resume seguro; o phase checkpoint existe para revisar e reverter um conjunto de mudanças. Tratar os dois com a mesma regra foi o que multiplicou os micro-event commits.

Quando o trabalho não tem autorização para commit, a regra é ainda mais simples. O fim da revisão não cria um estado COMMITTED ou CLOSED. O candidato à integração permanece congelado, e não é registrado como uma conclusão durable até existir um checkpoint real.

Mantive a verificação dos workers nos reports e a retirei dos documentos aggregate

No trabalho paralelo, cada worker produz comandos executados, resultados de verificações, hunks sobrepostos e restrições restantes. Repetir tudo isso no TODO raiz, no README e nos requisitos apenas aumenta a quantidade de documentos que o coordinator precisa ler.

As evidências detalhadas de cada worker ficam em reports imutáveis e no Git diff; o current-state guarda apenas a conclusão integrada, o impacto atual e o caminho da evidência. O coordinator revisa cada report, mas não trata um report como um commit. Vários reports da mesma phase podem compartilhar um único checkpoint depois da verificação integrada.

Com essa separação, os documentos aggregate ficam menores sem perder as verificações detalhadas. A próxima session lê primeiro o estado atual e só desce até os reports vinculados e o Git evidence quando precisa entender a base da decisão.

A ordem de resume contrariava a regra de owner

Depois de organizar as regras, revisei o fluxo inteiro e encontrei uma contradição inesperadamente básica. O procedimento inicial mandava ler primeiro o README e só depois o todo.md.

O README dizia para não duplicar o estado volátil, mas o procedimento real de resume lia o router antes do current-state. Se restasse ali algum texto antigo sobre o estado, a primeira decisão já poderia seguir na direção errada.

Por isso, alterei a ordem inicial. Primeiro, o canonical current-state informa o Runtime atual, o blocker, a phase e a próxima tarefa. Depois, o README e o router de documentos mostram os limites do repository e o documento leaf necessário. As decisões de produto estáveis são lidas no current-direction, e o contrato de comportamento real, nos requirements.

Adicionar apenas uma tabela de owners não bastava. A ordem real de leitura, seja por uma pessoa ou por um Agent, também precisava seguir essa relação de propriedade.

Escopo atual da aplicação e limitações restantes

Essa estrutura foi aplicada às regras de trabalho compartilhadas, ao routing de documentos do Operations Automation, ao manifest de documentação de mudanças e ao protocol de coordination paralela. O skill validator, a verificação de sincronização da documentação e a inspeção do diff passaram. No entanto, as mudanças ainda estão apenas no local working tree e não foram commitadas nem deployed.

Também não reescrevi retroativamente todos os documentos existentes. O histórico e os reports detalhados foram preservados; somente quando o mesmo fato de current-state entra em conflito entre documentos ativos ele é reduzido a uma referência ao owner. Antes de eliminar cada documento antigo, era mais importante impedir que ele voltasse a ser lido como authority do trabalho atual.

Agora, a qualidade da atualização da documentação não é medida pela quantidade de lugares alterados. O critério é conseguir ler um único lugar depois de uma compactação ou handoff sem errar a phase atual nem a próxima tarefa, e ainda conseguir rastrear as evidências detalhadas quando necessário.