Contratos de Implementação Resumíveis

Visão Geral

Transforme uma solicitação de implementação grande e majoritariamente definida em um contrato de repositório que um novo agente possa ler, atualizar, verificar e retomar sem reconstruir o projeto a partir do histórico de conversas. Mantenha a intenção estável separada do estado de execução mutável e exija evidências antes que qualquer tarefa seja considerada completa.

Este é um padrão de documento neutro em relação a ferramentas. Ele não depende, substitui ou configura recursos de objetivo, tarefa, plano ou projeto integrados de nenhuma plataforma de agente.

Esta habilidade preenche a camada entre o planejamento e a execução. Ela não substitui a descoberta de produto, o design técnico detalhado, a governança de estado em todo o projeto ou a auditoria retrospectiva.

Quando Usar Esta Habilidade

Use-a quando o trabalho:

• Abrange múltiplas sessões, agentes, branches ou janelas de contexto;
• Possui dependências ou critérios de aceitação que devem sobreviver à interrupção;
• Necessita de um ponto de retomada exato em vez de uma passagem de bastão narrativa;
• Pode parecer completo antes que evidências de tempo de execução, artefatos, UI ou testes existam;
• Deve preservar trabalho parcial e alterações não relacionadas no repositório.

Evite usá-la para uma tarefa pequena que possa ser concluída e verificada em uma única sessão. Se os requisitos ainda não estiverem definidos, resolva-os antes de congelar o contrato de implementação.

Reutilizar Documentos de Projeto Existentes

Inspecione o repositório antes de criar arquivos. Reutilize documentos equivalentes e os nomes estabelecidos do projeto quando a propriedade deles for clara. Para trabalho substancial de múltiplas sessões, o conjunto mínimo de documentos lógicos é:

Estes podem viver juntos sob docs/<contract-slug>/ ou seguir um layout de repositório existente. Um GOAL.md existente, especificação ou breve de execução pode possuir o papel de contrato; não o renomeie ou crie arquivos paralelos apenas para corresponder a esta habilidade.

Definir Autoridade do Documento

• As instruções do proprietário atual e as instruções aplicáveis do repositório governam a autorização e o escopo.
• IMPLEMENTATION_CONTRACT.md, ou seu equivalente existente no repositório, possui o contrato de implementação. Não o altere silenciosamente para se adequar ao código atual.
• A árvore de trabalho, branch, commit, artefatos produzidos e verificações executadas são a verdade para o estado da implementação.
• Os arquivos de rastreamento resumem esse estado; eles não substituem evidências contrárias no disco.

Quando documentos e realidade discordarem, reconcilie o status a partir das evidências, preservando a intenção do contrato. Escalone qualquer conflito que alteraria materialmente o escopo, o comportamento ou a aceitação.

Escrever um Contrato Autocontido

Um novo agente deve ser capaz de entender o trabalho a partir do contrato sem a conversa original. Inclua apenas o necessário para executar corretamente:

1. resultados objetivos e observáveis;
2. linha de base atual e restrições importantes;
3. trabalho incluído, exclusões e limites de autorização;
4. regras de operação, incluindo política de interrupção e validação;
5. tarefas com IDs estáveis, dependências, aceitação e pontos de interrupção;
6. definição final de conclusão e requisitos de passagem de bastão.

Use IDs de tarefa e subtarefa estáveis como T03 e T03.2. Nunca os renumerar após o início da execução; adicione novos IDs ou marque explicitamente o trabalho obsoleto.

Cada tarefa deve usar este formulário compacto:

### T03 - <observable task outcome>

- [ ] T03.1 <first implementation slice>
- [ ] T03.2 <second implementation slice>

Dependencies: T01

Acceptance:
- <observable behavior or artifact>
- <required focused check and evidence>

Breakpoint:
- Update TASKS.md, VALIDATION.md, and CHECKPOINT.md after the accepted slice.

Escreva a aceitação em termos de aprovação/reprovação. A criação de arquivo, a presença de código ou a reivindicação de conclusão de um agente não é aceitação, a menos que esse seja genuinamente o requisito completo.

Ler Antes de Agir

No início de uma sessão ou após uma interrupção, leia nesta ordem:

1. instruções aplicáveis do repositório;
2. o contrato de implementação;
3. TASKS.md, CHECKPOINT.md, DECISIONS.md e VALIDATION.md;

…