Especificação do DWP

Versão 4.0.0. Status: Estável. Este documento é a especificação normativa da metodologia Deep Work Plan (DWP). As palavras-chave MUST, MUST NOT, SHOULD, SHOULD NOT e MAY devem ser interpretadas conforme descrito na RFC 2119.

Aditivo em 2.4.0, sem alterações incompatíveis. (1) A seção Superfície tocada — o contrato entre o que uma tarefa muda e o que deve ser validado, com seleção de gate por classe de risco (isolada / costura / compartilhada-núcleo / desconhecida); (2) a validação completa passa a ser um requisito de estado final executado no único Final Review obrigatório do plano, com regras explícitas de reutilização de evidência; (3) as decisões de skills por tarefa passam para a tarefa que as origina, e o Executive Report passa a ser opcional, mediante solicitação; (4) um fluxo create consciente do modo — o modo trust materializa diretamente preservando a análise e as verificações de qualidade; (5) materialização de planos Lite em primeiro lugar — o create guiado produz um plano Lite diretamente executável em vez de um rascunho não executável, promovível a um plano Full a qualquer momento (veja Planos Lite); e (6) uma matriz de compatibilidade explícita: os planos e repositórios de versões anteriores permanecem conformes.

Padrão 4.0.0. O salto de versão alinha o número do padrão com a linha de produtos — 2.x é histórico e não existe padrão 3.x — e não muda nenhum requisito em relação a 2.4.0. Planos e repositórios de versões anteriores continuam conformes.

Definição

Um Deep Work Plan é um artefato estruturado, exclusivamente em markdown, que descreve uma tarefa de engenharia complexa decomposta em unidades de trabalho sequenciais e revisáveis, projetado para ser criado, executado e mantido por agentes de código de IA trabalhando de forma autônoma.

O DWP é orientado a especificação: o plano é a especificação, e os agentes DEVEM (MUST) executar contra seus critérios de aceitação e validation gates explícitos, em vez de improvisar. A especificação — e não uma transcrição de chat — é a fonte de verdade duradoura, de modo que o trabalho é verificável e retomável entre sessões e agentes. É também engenharia de harness tornada portátil: o contexto, o loop de controle, as salvaguardas e o estado retomável que tornam um agente confiável são instalados no próprio repositório como markdown puro, de modo que qualquer agente conforme PODE (MAY) pilotar o repositório sem um framework específico de ferramenta.

Fluxo create — etapa única, consciente do modo

O fluxo create reúne uma única vez o objetivo, o contexto, as restrições e o esboço de tarefas, realiza sua análise de requisitos (escopo, ordenação de dependências entre tarefas, seleção de validação a partir da Superfície tocada, tier de rigor proporcional) e então materializa de acordo com o modo que o programador escolheu:

• Modo guiado (padrão). O fluxo materializa um plano Lite diretamente — uma proposta compacta e já executável com registros de tarefa {#task-N} em linha, revisável em uma única passagem — e pede ao programador que o mantenha como Lite, o promova a um plano Full, solicite alterações, ou pare. Nenhum rascunho intermediário não executável é produzido.
• Modo trust (trust / auto). O fluxo materializa a representação escolhida (Lite, ou Lite seguido imediatamente pela promoção a Full) diretamente, sem etapa de revisão — o programador abriu mão dela. A análise de requisitos, a ordenação de dependências e uma verificação de qualidade do plano continuam a ser executadas: trust abre mão da revisão, não da análise. Um plano em modo trust é registrado como pré-aprovado para execução não supervisionada.

Ambos os modos decidem o formato do plano (Lite ou Full) como parte da mesma análise de requisitos, nunca como uma reflexão tardia. Veja Planos Lite para o ciclo de vida completo de representação, criação-e-seleção, e promoção.

Estrutura do plano

Um plano DEVE (MUST) ser um diretório em .dwp/plans/ chamado PLAN_<slug>/, em uma de duas representações:

• Full. O diretório DEVE (MUST) conter README.md (visão geral do plano, objetivo, tabela de tarefas e status), um arquivo por tarefa chamado <n>.task_<slug>.md, e PROGRESS.md (um registro contínuo da execução).
• Lite. Registros de tarefa compactos e totalmente executáveis vivem em linha em README.md atrás de âncoras estáveis {#task-N} em vez de arquivos de tarefa separados — cada registro ainda carrega um objetivo, uma Superfície tocada, critérios de aceitação, validação e um Completion & Log. PROGRESS.md continua OBRIGATÓRIO (REQUIRED). Um plano Lite PODE (MAY) ser promovido a Full a qualquer momento. Veja Planos Lite para o ciclo de vida completo, em vez de duplicá-lo aqui.

Um plano PODE (MAY) adicionalmente carregar a camada de estado legível por máquina: manifest.json (identidade estática, escrito uma vez na materialização) e state.json (estado de execução ao vivo por tarefa). A camada de estado é RECOMENDADA (RECOMMENDED) para novos planos e OBRIGATÓRIA (REQUIRED) para execução não supervisionada e para espaços de trabalho de agentes sem git. Veja Estado do plano.

Anatomia da tarefa

Arquivo de tarefa

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Cada arquivo de tarefa DEVE (MUST) conter estas dez seções, em ordem:

1. Goal — uma declaração de um parágrafo do que a tarefa alcança.
2. Context — contexto, links e por que esta tarefa existe.
3. Superfície tocada — o contrato entre o que a tarefa muda e o que deve ser validado.
4. Steps — ações ordenadas e concretas a executar.
5. Acceptance criteria — uma lista de verificação de condições que definem o concluído.
6. Validation — comandos ou testes a executar para verificar, selecionados a partir da Superfície tocada.
7. Files — caminhos que se espera criar ou modificar.
8. Dependencies — outras tarefas ou pré-requisitos externos.
9. Risks — o que pode dar errado e as mitigações.
10. Completion & Log — um marcador de status mais notas cronológicas.

Uma tarefa PODE (MAY) adicionalmente incluir uma seção Delta (RECOMENDADA para alterações de comportamento em brownfield — veja abaixo) e uma seção Rollback (RECOMENDADA para migrações, alterações de infraestrutura ou implantações).

A Superfície tocada

A Superfície tocada é o contrato entre o que uma tarefa muda e o que deve ser validado. Ela existe para que a validação seja selecionada pelo efeito, não pelo hábito, e para que um leitor posterior possa ver por que um gate foi escolhido. Uma tarefa que altera o comportamento DEVE (MUST) registrar:

• Superfície planejada — os caminhos, módulos, pacotes ou configuração que a tarefa pretende mudar, escritos antes de editar.
• Superfície real — a lista reconciliada após editar, tomada do diff real. O agente DEVE (MUST) reconciliar as superfícies planejada e real antes de selecionar o gate.
• Consumidores afetados — módulos, pacotes ou serviços que dependem da superfície real, até onde o mapeamento documentado do repositório conseguir estabelecer. Onde não conseguir, a entrada DEVE (MUST) dizê-lo.
• Classe de risco — uma de: isolada (confinada a um módulo e seus testes); costura (altera um contrato, persistência, roteamento, serialização, autenticação ou o cabeamento do framework entre colaboradores); compartilhada/núcleo (importada amplamente, ou uma mudança de dependência, migração, configuração de build/testes, schema ou cadeia de ferramentas); desconhecida (o mapeamento está ausente, desatualizado ou não verificado).
• Mapeamento de testes usado — qual mapeamento ou ferramenta documentada produziu a seleção.
• Gate selecionado e motivo — os comandos exatos e por que cobrem a superfície real.

Arquivos de configuração, schemas, manifestos de dependências, templates, fixtures, migrações e arquivos de instruções de agente podem mudar o comportamento e DEVEM (MUST) ser classificados pelo seu efeito, nunca pela extensão do arquivo. Uma tarefa que muda apenas prosa, comentários ou artefatos de pesquisa PODE (MAY) declarar a superfície como não aplicável e ainda assim executa as verificações não runtime do repositório.

A seção Delta (alterações em brownfield)

A maior parte do trabalho real modifica comportamentos existentes em vez de criar novos. Uma tarefa que altera o funcionamento de um sistema existente DEVERIA (SHOULD) incluir uma seção Delta descrevendo a mudança como um contrato explícito de antes/depois, usando três títulos de lista:

• ADDED — comportamento que existe depois da tarefa e não existia antes.
• MODIFIED — comportamento que existe em ambos, declarado como was: … → now: ….
• REMOVED — comportamento que existia antes e foi intencionalmente removido depois.

Cada entrada DEVE (MUST) ser um comportamento observável — a resposta de um endpoint, um flag de CLI, um estado de UI, um valor padrão — não um detalhe de implementação. A seção Delta é o diff do revisor no nível de comportamento: os critérios de aceitação verificam as entradas ADDED/MODIFIED, e as entradas REMOVED são a licença explícita para excluir. Qualquer coisa não listada como REMOVED DEVE (MUST) continuar funcionando.

Validation gates — selecionados por classe de risco

A validação é o gate que transforma uma afirmação de conclusão em evidência dela: uma tarefa NÃO DEVE (MUST NOT) ser marcada como concluída até que todo comando de sua seção Validation tenha sido executado e aprovado. O gate de uma tarefa que altera o comportamento é selecionado a partir de sua Superfície tocada reconciliada, por classe de risco:

Uma mudança de comportamento DEVE (MUST) produzir uma seleção de testes não vazia e relevante — um seletor inválido ou um executor que selecionou zero testes não é cobertura. Onde o mapa de testes do repositório estiver desatualizado, deriva-se a invocação correta e registra-se a atualização do mapeamento; um pequeno comando faltante nunca exige uma execução completa de onboarding. Onde não existir uma invocação delimitada, aplica-se a suíte completa aplicável — comportamento legado, nunca um erro.

Quando uma tarefa adiciona nova funcionalidade central ou altera de forma material o comportamento existente, seus critérios de aceitação DEVEM (MUST) incluir cobertura de testes automatizados para o comportamento novo ou alterado, e sua validação executa os testes do repositório junto com as verificações de lint, type-check e formatação — não apenas o build. Os testes existentes DEVEM (MUST) permanecer verdes.

Validação de estado final

Os gates por tarefa validam o que cada tarefa tocou; eles não substituem a validação do plano como um todo. Antes de um plano se completar, a validação completa aplicável do repositório DEVE (MUST) executar e passar sobre o estado final relevante, após a última mudança substancial — no Final Review. Execuções mais amplas anteriores acontecem em limites de integração ou após mudanças compartilhadas/núcleo, não segundo um cronograma baseado na contagem de tarefas. Um resultado aprovado PODE (MAY) ser reutilizado apenas com evidência de que as entradas relevantes são equivalentes; caso contrário, é reexecutado. Cada execução de gate deixa um registro conciso: comando, escopo, revisão, resultado e um caminho de evidência.

Disciplina de segurança

A segurança é de primeira classe da mesma forma que os testes, e segue o mesmo modelo de duas camadas: disciplina por tarefa enquanto o trabalho acontece, mais o passe de segurança do Final Review sobre todo o conjunto de alterações ao final. Sempre que uma tarefa toca autenticação ou autorização, o tratamento de entradas, secrets ou configuração, a superfície de rede, de arquivos ou de shell, ou dependências:

• Seus critérios de aceitação DEVEM (MUST) declarar as expectativas de segurança da mudança — entrada validada e escapada, sem material secreto no código ou nos fixtures, verificações de autenticação preservadas ou reforçadas —, de forma coerente com docs/SECURITY.md.
• Todo commit DEVE (MUST) ser confirmado livre de secrets ou credenciais antes de ser incorporado, incluindo fixtures de teste e exemplos de documentação. Um secret em um commit já enviado DEVE (MUST) ser tratado como vazado e rotacionado, não apenas removido.
• Onde o trabalho sensível à segurança for substancial, uma tarefa de hardening dedicada DEVERIA (SHOULD) ser colocada imediatamente após as tarefas de implementação e antes da tarefa de testes abrangentes, de modo que as descobertas sejam corrigidas antes que os testes codifiquem o comportamento e cada descoberta se torne um caso de regressão em vez de retrabalho.

Essa disciplina por tarefa não substitui o passe de segurança do Final Review: as verificações por tarefa capturam os problemas no commit onde nascem, enquanto o gate final audita todo o plano — incluindo as próprias tarefas de testes e documentação.

Ciclo de vida do plano — o Final Review

Todo plano conforme redigido sob esta versão termina com exatamente uma tarefa obrigatória: o Final Review (tarefa N). Duas responsabilidades que versões anteriores colocavam em tarefas de encerramento separadas são realocadas: as decisões de skills passam para a tarefa que produziu o padrão, e o Executive Report passa a ser um artefato opcional, mediante solicitação. Nada do passe de segurança é relaxado.

O Final Review DEVE (MUST), em ordem:

(a) Passe de segurança — revisar todo o conjunto acumulado de alterações do plano em busca de secrets embutidos, riscos de injeção, nova superfície de ataque, autenticação enfraquecida e dados sensíveis em logs ou documentação; auditar as dependências introduzidas; verificar que o docs/SECURITY.md ainda reflete a realidade; escrever o relatório de revisão de segurança mesmo quando estiver limpo. Uma descoberta crítica é corrigida — ou explicitamente aceita pelo usuário — antes de o plano se completar.

(b) Validação de estado final — a validação completa aplicável do repositório executa e passa sobre o estado final relevante.

(c) Reconciliação de skills — cada tarefa carrega uma disposição de skills e cada candidata registrada tem uma disposição; não há um segundo relatório de descoberta.

(d) Conclusão — reportar a conclusão com entregáveis, evidência de validação e limitações; oferecer o Executive Report uma única vez. O plano fica completo independentemente de a oferta ser respondida.

O Final Review executa sequencialmente após todas as demais tarefas e nunca é colocado em um grupo paralelo.

Decisões de skills por tarefa

A pergunta “este trabalho criou um padrão reutilizável que mereça uma skill ou um agent?” é respondida dentro da tarefa que produziu o padrão, enquanto sua evidência está em contexto. O Completion & Log de cada tarefa carrega uma disposição de skills: nenhuma, atualizar uma skill existente, criar um artefato nomeado, ou um adiamento com motivo. A autoria justificada acontece dentro dessa tarefa, antes de seu validation gate e de seu commit, após verificar duplicados no catálogo existente.

Executive Report — opcional, mediante solicitação

O Executive Report não é mais uma tarefa obrigatória. Na conclusão, o agente o oferece uma vez; ele é gerado apenas mediante solicitação explícita, atendido a partir de evidência duradoura sem reproduzir o plano. Sem resposta, ou em uma execução não supervisionada, o plano fica completo sem nenhum relatório gerado.

Protocolo de conclusão de tarefa

Após passar pela validação e antes de avançar para a próxima tarefa, o agente DEVE (MUST), em ordem: (1) marcar a tarefa como [x] no README do plano; (2) incrementar o contador de status do plano; (3) preencher o Completion & Log da tarefa sem valores de placeholder; (4) adicionar uma entrada de 3 a 5 itens ao PROGRESS.md; (5) fazer commit (onde o plano faz commits) com o formato {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) onde o plano carrega a camada de estado, reescrever o state.json atomicamente — tarefa completed, registros de gate, registro de resultado, hash de commit.

As seis etapas formam uma transação lógica única. Um agente interrompido no meio do protocolo NÃO DEVE (MUST NOT) iniciar a próxima tarefa — ele deve terminar ou desfazer a conclusão parcial primeiro.

O protocolo de retomada do DWP

A retomada DEVE (MUST) ser possível apenas a partir dos arquivos do plano mais o log do git, sem estado externo. Em um workspace sem git — veja Arquétipos §3 — o state.json do plano é OBRIGATÓRIO (REQUIRED) e substitui o log do git.

Um agente que retoma — uma nova sessão, um agente diferente, um turno de daemon agendado ou uma sessão em nuvem que acorda — DEVE (MUST) realizar este ritual, em ordem:

1. Reancorar. Ler o README do plano: objetivo, diretrizes globais, a lista de tarefas.
2. Localizar o checkpoint. Encontrar a primeira tarefa não marcada no README; ler o log do git e o status do git (ou o checkpoint do state.json onde o git está ausente).
3. Reconciliar o estado. Onde o state.json existe, compará-lo com as caixas de seleção do README; em caso de dessincronização, regenerá-lo a partir do markdown antes de continuar.
4. Inspecionar a juntura. Ler o Completion & Log da tarefa no ponto de retomada e a última entrada do PROGRESS.md — a última base verificada da sessão anterior.
5. Smoke test. Executar a validação permanente mais barata do repositório para confirmar que o ambiente ainda funciona antes de construir sobre ele. Um smoke test com falha é investigado primeiro, não construído sobre.
6. Continuar atomicamente. Executar exatamente a próxima tarefa; não agrupar à frente.

O agente DEVE (MUST) confiar nas marcações completed ([x]) e NÃO DEVE (MUST NOT) revalidar tarefas concluídas, a menos que o usuário solicite explicitamente, ou o smoke test falhe de uma forma que implique uma tarefa concluída.

O loop de execução

O DWP define cinco operações:

• create — Gerar um novo plano a partir de um objetivo.
• execute — Executar o plano tarefa a tarefa.
• refine — Modificar um plano existente.
• resume — Retomar um plano interrompido.
• status — Relatar o status do plano sem executar.

Espaço de trabalho de saída

Espaço de trabalho de saída

• .dwp/ ignorado pelo git · descartável
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ relatórios
• SECURITY_REVIEW.md revisão de segurança
• EXECUTIVE_REPORT.md relatório executivo

Todos os artefatos do DWP DEVEM (MUST) viver em um diretório .dwp/ ignorado pelo git, na raiz do repositório.

Estado do plano legível por máquina

Um plano PODE (MAY) carregar a camada de estado legível por máquina — manifest.json (identidade estática) e state.json (estado ao vivo por tarefa, registros de validation gate, registros de resultado, checkpoint, estado bloqueado). O plano markdown permanece a fonte de verdade; a camada JSON é uma projeção derivada, regenerada em pontos de protocolo e reconciliada na retomada.

A camada de estado é RECOMENDADA (RECOMMENDED) para novos planos, OBRIGATÓRIA (REQUIRED) para execução não supervisionada e OBRIGATÓRIA (REQUIRED) para espaços de trabalho de agentes sem git. Veja a definição normativa completa em Estado do plano.

Rigor proporcional

O rigor DEVE (MUST) ser proporcional ao trabalho. Cerimônia em mudanças triviais é uma falha de metodologia, não segurança extra. Todo trabalho se enquadra em exatamente um tier:

Um agente solicitado a criar um plano para trabalho de tier micro DEVE (MUST) dizer que um plano é desproporcional e oferecer a forma inline. Uma pasta de plano NÃO DEVE (MUST NOT) ser criada para uma mudança trivial de arquivo único.

O trabalho de tier micro ainda mantém os inegociáveis: um objetivo explícito, um validation gate que é executado e aprovado, e disciplina de testes para mudanças de comportamento. O tier muda o empacotamento, nunca os gates.

Quando o escopo cresce no meio do caminho — uma micro tarefa revela escopo real, um plano standard cria sub-repositórios — o agente DEVE (MUST) parar e promover o trabalho ao próximo tier em vez de estender o atual.

Compatibilidade

Os planos e repositórios de versões anteriores permanecem conformes, e um verificador de conformidade DEVE (MUST) distinguir um artefato legado conhecido (aceito) de um artefato que declara esta versão e é objetivamente inválido sob ela (rejeitado):

Versionamento

Esta especificação segue o versionamento semântico.