marcioaltoe/write-tasks

Write Tasks

Transforme docs/specs/<slug>/_prd.md (e _techspec.md, quando presente) no grafo executável de tarefas: um arquivo task_NN.md por tarefa mais _tasks.md, o manifesto de onde implement-task e o Daemon Roundfix se baseiam para agendamento. Os artefatos são o contrato — uma sessão de agente nova deve ser capaz de pegar um arquivo de tarefa e construí-lo sem outro contexto além da pasta de especificação.

Planejamento de nível leve

Uma Tarefa com complexity: low que não é QA e não declara Caminho Governado executa no nível leve. O autor pode executar roundfix spec judge <slug> --stage tasks para uma sugestão de nível consultiva antes do Pull Request de planejamento ser mesclado; a sugestão não controla o despacho.

Pré-condições

$ARGUMENTS nomeia a especificação. _prd.md deve existir. Se _techspec.md estiver faltando em uma funcionalidade com superfície arquitetural real, execute write-techspec primeiro e depois decomponha — criar o artefato faltante é a resolução, nunca um motivo para parar e pedir permissão. Sob trabalho autônomo, isso não precisa de confirmação: direcionar trabalho autônomo autoriza toda a cadeia de criação para cada Especificação já na fila aprovada, conforme docs/agents/autonomous-work.md. Peça aceitação apenas quando for explicitamente dito para decompor sem uma tech spec, e então compense com uma exploração mais profunda do código antes de decompor.

Verificação prévia de Restrições de Projeto

Execute esta verificação prévia antes de derivar ou aprovar uma decomposição:

1. Classifique a Especificação. Uma Especificação sob o diretório de arquivo resolvido (docs/history/specs/ para a raiz docs/specs embutida, ou <spec-root>/_archived/ para uma raiz externa ou não padrão), ou uma comprovadamente concluída antes deste contrato se aplicar, é uma Especificação legada concluída ou arquivada. Deixe cada artefato legado byte-idêntico: não preencha, reformate, regenere ou reescreva.
2. Para cada Especificação ativa, não arquivada e ainda não concluída, exija que o PRD e cada TechSpec presente contenham seções Project Constraints completas. Cada seção deve registrar Identifier strategy, Authentication and HTTP, Active ADR obligations e Tooling authority como aplicável ou não aplicável com um motivo, e cada linha deve citar seu caminho de origem docs/agents/ operativo.
3. Se qualquer artefato ativo estiver ausente ou incompleto, recuse criar ou atualizar _tasks.md ou qualquer arquivo de Tarefa. Nomeie toda linha, motivo ou caminho de origem faltante e envie a Especificação de volta à skill de autoria proprietária.
4. Inspecione as fatias propostas para qualquer criação, edição, renomeação, movimentação ou exclusão de configuração de ferramental de repositório, scripts, arquivos de ignorar, declarações de plugin ou fixações de versão. Tal trabalho é autorizado apenas quando o PRD e o TechSpec presente registram autorização do mantenedor e os arquivos exatos delimitados pelo repositório que cobre. Uma solicitação de implementação genérica, aprovação de configuração ou atribuição de Tarefa não é autorização. Sem ambos a autorização e os arquivos delimitados, recuse a decomposição.
5. Resolva o registro operativo em <spec-root>/<slug>/_authorization.md para toda fatia de ferramental. Um registro ausente, um registro proposed ou um registro sem data de concessão não autoriza nada; recuse a decomposição até que uma concessão operativa exista. Uma concessão nova ou ampliada deve chegar na ancestralidade alvo antes da entrega squash consumidora, então a concessão ou emenda não pode ser dobrada na mudança que autoriza.
6. Copie a lista de arquivos delimitados no escopo e critérios de aceitação de cada Tarefa de ferramental autorizada. A Tarefa pode mudar apenas esses caminhos mais seu próprio arquivo de Tarefa; divida qualquer trabalho que precise de um limite diferente.
7. A lista operations do registro deve conceder toda operação de entrega que a Especificação usará. roundfix deliver start recusa um registro sem implement, commit, push, pull_request ou merge; uma Especificação sem Caminho Governado registra paths: [].
8. Um commit de Tarefa mantém um arquivo executável não rastreado apenas quando seu caminho exato está listado sob executáveis no registro de autorização da Especificação; todo outro executável não rastreado é recusado. A lista deve estar no alvo de entrega antes da Execução lê-la. Commits de QA Report e Batch nunca mantêm um executável não rastreado. Um repositório com core.fileMode false registra o arquivo como 100644.

Dependências permanecem de propriedade apenas de _tasks.md; status da Tarefa permanece de propriedade apenas de cada arquivo de Tarefa. A verificação prévia nunca move nenhuma responsabilidade.

Código para outro sistema operacional é verificado construindo seu código não de teste para esse sistema, com um exemplo como GOOS=windows go build -buildvcs=false ./<package>, e nunca com go vet, que também compila testes escritos para o host.

Regras de propriedade (o que vive onde e por quê)

• Dependências vivem apenas no grafo _tasks.md. Nunca em arquivos de tarefa. Duas cópias de uma aresta é como grafos derivam.
• Status vive apenas no frontmatter de cada arquivo de tarefa. _tasks.md é dono da topologia, não do progresso — agendadores releem arquivos de tarefa para estado.
• Tipo de Tarefa é obrigatório em todo arquivo de tarefa. Use exatamente um de backend, frontend, data, infra, docs, test, chore ou qa. Reserve qa para o gate terminal único criado nomeado pelo campo qa: do manifesto. O Comando de Implementação consome este valor para roteamento e rejeita valores ausentes ou desconhecidos; nunca deixe um placeholder ou infira o tipo mais tarde.
• Referências de conteúdo, nunca duplicatas. Arquivos de tarefa apontam para seções de PRD/TechSpec pelo nome; uma tarefa que reafirma a especificação fica desatualizada na primeira vez que a especificação é emendada. Vincule uma fonte adotada em seu caminho pós-adoção na Especificação proprietária com um destino relativo àquele arquivo de Tarefa, nunca em seu caminho de proveniência pré-adoção. Uma Especificação secundária vincula a cópia do proprietário primário e não adota nada. O arquivo do proprietário realiza um Relink de Arquivo: promove essa cópia para docs/references/ e reescreve os links da Especificação secundária, então a fonte mantém um proprietário e a Especificação secundária não precisa de cópia (ADR-0260, ADR-0083).
• Entradas de contexto são caminhos rotulados. Adicione ## Context apenas quando a Tarefa precisar de instrução específica ou caminhos de interface além do pacote de especificação padrão. Use marcadores no formato - instruction: <path>, - interface: <path>, - creates: <path> ou - deletes: <path>. Caminhos devem ser limpos, relativos ao repositório e únicos; uma Tarefa pode declarar no máximo 50 entradas únicas. O Daemon reserva esses caminhos antes de preencher o Pacote de Contexto de Especificação de 200 caminhos com arquivos alterados anteriores.
• Edições declaradas e caminhos governados são explícitos. Cada caminho que uma Tarefa edita é declarado sob interface: ou creates:; cada caminho que ela remove é declarado apenas sob deletes:, nunca interface: e nunca instruction:. Uma Tarefa que lê um arquivo antes de removê-lo ainda o lista uma vez, sob deletes:. Uma exclusão é ignorada por verificações de referência não resolvida e conta no escopo, auditorias de colisão de Caminho Governado e Onda. O Daemon recusa assentamento antes da Verificação quando uma exclusão declarada ainda existe, com deletes: <path> still exists. Um caminho instruction: é somente leitura e nunca faz duas Tarefas colidirem. Cada Tarefa que muda um comando declara o único arquivo de comando que muda: .agents/skills/roundfix/references/<command>.md com seu espelho, e docs/user-guide/commands/<command>.md, nunca o SKILL.md ou commands.md da habilidade, a menos que mude o próprio arquivo de entrada. Duas Tarefas que declaram o mesmo arquivo não podem compartilhar uma Onda, então Tarefas que mudam comandos diferentes podem executar juntas e Tarefas que mudam o mesmo comando precisam de uma aresta entre elas. Um Caminho Governado declarado ou lido pela Verificação deve aparecer em _authorization.md paths: e em ambas as linhas bounded files:, ou a criação é recusada com SC-TOOLING-UNDECLARED. Uma Tarefa nomeando uma superfície CLI nomeia sua habilidade ou guia ela mesma ou através de uma Tarefa da qual depende; caso contrário, é relatada com SC-CLI-UNDOCUMENTED.

O Daemon registra um caminho que uma Tarefa mudou sem declará-lo sob ## Recorded paths no commit. A auditoria de escopo de QA conta esse caminho registrado como declarado, e o registro divulga uma mudança e não reserva nada. Declarar todo caminho previsível continua sendo a regra.

Um helper de teste, fake, fixture ou golden que duas Tarefas podem cada uma mudar é um caminho previsível. Declare-o sob interface: em cada Tarefa que possa mudá-lo, para que roundfix spec check --strict relate SC-WAVE-COLLISION enquanto a Especificação ainda está sendo criada e a aresta needs que nomeia executa essas Tarefas em série. O registro não reserva nada, e uma Tarefa concluída nunca colide: o commit de assentamento de uma Tarefa é evidência de colisão apenas enquanto uma das duas Tarefas não está concluída, como uma Tarefa reaberta para pending, então duas Tarefas de uma Onda que ambas concluem após mudar o mesmo arquivo não declarado nunca são recusadas. Declarar o arquivo é a única proteção.

Tarefas de Habilidades para Superfícies de Comportamento Alteradas

Leia o Mapa de Cobertura de Habilidades do repositório em docs/references/skill-coverage.json quando existir. Para cada Superfície de Comportamento coberta cuja fonte uma Tarefa não QA declara sob interface:, creates: ou deletes:, inclua uma Tarefa de habilidades não QA que declara um de seus arquivos de habilidade cobertos sob interface: ou creates:. SC-SKILLS-UNTASKED relata uma superfície sem tal Tarefa.

Quando a mudança não precisa de texto de habilidade, registre - unchanged: <surface id> — <reason> na seção opcional ## Skills do PRD e inclua uma Tarefa não QA declarando o mapa sob interface: ou creates: para registrar a Revisão de Cobertura. A entrada sozinha não desculpa a superfície. SC-SKILLS-MALFORMED relata uma entrada de outra forma, uma superfície desconhecida ou um motivo em branco. Ambas as regras começam no commit que adicionou o mapa; repositórios sem um as pulam.

Uma Tarefa não QA declarando uma página Markdown sob docs/user-guide/ sob interface:, creates: ou deletes: também deve declarar docs/references/behavior-surfaces.json sob interface: ou creates: e nomear o passo -record-skill-coverage em um requisito. Outra Tarefa não pode cobri-la: o assentamento da própria Tarefa do guia verifica sua impressão digital. Os Limites de _authorization.md da Especificação nunca devem proibir esse registro. SC-SURFACE-RECORD-UNTASKED relata qualquer lacuna do estágio de Tarefas, sem horizonte, em repositórios que têm o registro.

Regras de decomposição

Código para outro sistema operacional é verificado construindo seu código não de teste para esse sistema, com um exemplo como GOOS=windows go build -buildvcs=false ./<package>, e nunca com go vet, que também compila testes escritos para o host.

• Fatias verticais. Cada tarefa entrega um caminho estreito mas completo através de cada camada que toca, demonstrável ou verificável por si só — uma bala traçadora, não uma camada ("todos os esquemas" é uma tarefa errada; "importações expiradas tentam novamente e exibem seu status" é uma certa).

• Pré-fatoração primeiro. Quando uma fatia precisa do terreno preparado, faça disso sua própria tarefa líder: torne a mudança fácil, depois faça a mudança fácil.

• Caracterize superfícies externas durante a criação. Quando uma Especificação cruza uma superfície externa como um adaptador, contrato ou banco de dados, crie uma Tarefa de caracterização que registra o que o limite real faz, não o que um fake faz, para que uma premissa não suportada falhe enquanto a Especificação ainda está sendo criada em vez de no gate de QA.

  Liste-a em needs, não meramente antes no arquivo. Cada Tarefa cuja premissa depende da caracterização nomeia essa Tarefa em sua entrada needs em _tasks.md. Ondas de execução são construídas apenas a partir de needs, então uma Tarefa que meramente aparece depois no manifesto pode executar na mesma onda que a caracterização da qual depende e ler um limite que ninguém caracterizou ainda. Ordem de arquivo não é uma dependência.

  Uma Tarefa de caracterização toca um limite real, então limite-a explicitamente. Seu arquivo declara o alvo que alcançará, pelo nome. Ela lê em vez de escrever, ou executa contra uma instância isolada que a própria Tarefa cria e remove; ela nunca caracteriza contra estado compartilhado ou de produção por padrão. Ela usa credenciais escopo naquele alvo e não mais amplas, honra cancelamento e limpa o que criou mesmo quando falha. Uma caracterização que deve escrever requer que essa escrita seja autorizada na Tarefa como qualquer outra ação irreversível é — registrar o que um limite faz não é autoridade para mudá-lo.

  Sua Verificação afirma o registro, nunca o limite. O Daemon executa os comandos declarados de ## Verification de uma Tarefa textualmente através do shell, uma vez contra a árvore inalterada antes de a vez do Agente existir e novamente no assentamento. Nada nesse caminho lê os limites acima: eles restringem o Agente, e o Daemon não é o Agente. Uma Verificação que alcança a superfície real, portanto, a alcança sem limites, duas vezes, inclusive antes de qualquer trabalho ser feito. Verifique a caracterização que a Tarefa registrou — sua forma, sua presença, o que Tarefas downstream lerão — e deixe a chamada de limite na vez do Agente, onde o alvo declarado da Tarefa, isolamento, credenciais e autorização de escrita se aplicam. Esta é a regra de hermeticidade que esses comandos já carregam, declarada onde a tentação de quebrá-la é mais forte: uma superfície externa viva é estado ambiente, e um comando que depende de um não é hermético.

• Dimensionado para uma sessão nova. Uma tarefa que um agente pode completar em uma única sessão com um contexto novo. Mais de ~7 subtarefas ou arquivos significa dividi-la.

• Testes embutidos, nunca separados. Os critérios de aceitação de cada tarefa incluem seus próprios testes; uma tarefa final de "escrever os testes" significa que as tarefas anteriores nunca foram concluídas.

• Implementável independentemente. Uma vez que suas needs são concluídas, uma tarefa não deve exigir nenhum outro trabalho inacabado — isso é o que permite execução paralela em worktrees mais tarde.

• Verificação deve ser hermética, portátil, comprovadora de efeito e de propriedade do Daemon. Os comandos ## Verification de cada tarefa devem ser satisfatórios em um worktree novo usando apenas a árvore de origem base (obtida com roundfix deliver init), sem estado ambiente, sem dependência de rede, sem arquivos fora da árvore de origem. Eles devem provar que a tarefa foi concluída — um comando que apenas compila ou apenas executa linter não prova nada a menos que seja acoplado a uma asserção sobre a saída. O Daemon executa esses comandos, não um agente; eles devem ser executáveis em um shell sem dependências de runtime de IA.