Estados da Especificação

Referência de máquina de estados para especificações — todos os 10 estados, transições e regras.

Toda especificação se move por um ciclo de vida de 10 estados. Transições são disparadas por ações de usuário, chamadas de ferramentas e avaliações automáticas.

Referência Rápida

Estado	Você deve…
`draft`	Começar a planejar — criar seu primeiro épico ou ticket
`planning`	Continuar construindo estrutura (épicos, tickets)
`specifying`	Continuar vinculando (dependências, blueprints)
`validating`	Revisar achados, corrigir lacunas
`ready`	Começar a implementação — lançar seu agente
`in_progress`	Monitorar painel, resolver bloqueios
`ready_for_review`	Disparar Implementation Review
`in_review`	Aguardar resultados, endereçar achados
`reviewed`	Confirmar conclusão
`completed`	Feito 🎉

Estados

Estado	Fase	Descrição
`draft`	Planejamento	Estado inicial. Especificação criada mas planejamento não iniciado.
`planning`	Planejamento	Épicos e tickets estão sendo definidos. Trabalho estrutural em progresso.
`specifying`	Planejamento	Dependências, blueprints e links cross-epic estão sendo estabelecidos.
`validating`	Planejamento	Verificações de qualidade rodando. Relatórios avaliando completude e consistência.
`ready`	Planejamento	Planejamento completo. Especificação passou no gate de Planning Review.
`in_progress`	Implementação	Work sessions ativas. Tickets sendo implementados.
`ready_for_review`	Implementação	Todos os tickets completados. Especificação aguardando review.
`in_review`	Implementação	Implementation Review em progresso. Gates de qualidade sendo avaliados.
`reviewed`	Implementação	Review passou. Todas as verificações de qualidade satisfeitas.
`completed`	Implementação	Todo trabalho finalizado. Especificação está fechada.

Tabela de Transições

Gatilho	De	Para	Condição
Épico criado	`draft`	`planning`	Primeiro épico adicionado
Ticket criado	`draft`	`planning`	Primeiro ticket adicionado
Dependência adicionada	`planning`	`specifying`	Operação de dependência ou blueprint realizada
Blueprint vinculado	`planning`	`specifying`	Blueprint anexado a um épico
Relatório solicitado	`specifying`	`validating`	Relatório ou verificação de qualidade disparada
Épico criado	`specifying`	`planning`	Mudança estrutural durante specifying
Épico criado	`validating`	`planning`	Mudança estrutural durante validating
Ticket criado	`specifying`	`planning`	Mudança estrutural durante specifying
Ticket criado	`validating`	`planning`	Mudança estrutural durante validating
Dependência adicionada	`validating`	`specifying`	Mudança de vinculação durante validating
Planning review passou	`validating`	`ready`	Planning gate passa o limite
Planning review passou	`planning`	`ready`	Planning gate passa (se invocado diretamente)
Planning review passou	`specifying`	`ready`	Planning gate passa (se invocado diretamente)
Work session iniciada	`ready`	`in_progress`	Primeira chamada `start_work_session`
Todos tickets completados	`in_progress`	`ready_for_review`	Todo ticket alcança `done`
Review iniciado	`ready_for_review`	`in_review`	`start_review_session` chamado
Review passou	`in_review`	`reviewed`	Implementation gate passa
Conclusão confirmada	`reviewed`	`completed`	Confirmação final
Todos tickets completados (sem review)	`in_progress`	`completed`	Todos tickets done e `requireImplementationReview` é `false`
Especificação reaberta	`completed`	`in_progress`	`reopen_specification` chamado
Especificação reaberta	`reviewed`	`in_progress`	`reopen_specification` chamado

O Corredor de Planejamento

Os três estados planning, specifying e validating formam o corredor de planejamento. Transições dentro deste corredor acontecem automaticamente baseadas no tipo de operação que você realiza:


planning <---> specifying <---> validating

Operações estruturais (criar épicos, criar tickets, deletar épicos) → movem para planning
Operações de vinculação (adicionar dependências, vincular blueprints) → movem para specifying
Operações de avaliação (solicitar relatórios, executar verificações) → movem para validating

Você não avança manualmente por esses estados. O SpecForge rastreia a natureza das suas operações e transiciona de acordo. O corredor é projetado para refinamento iterativo — alterne livremente entre criar estrutura, vincular dependências e verificar qualidade.

ℹ️ Você pode chamar o Planning Review de qualquer estado no corredor. Se ele passa, a especificação sai do corredor para ready independente de estar em planning, specifying ou validating.

Auto-Transições

Várias transições acontecem automaticamente sem ação explícita do usuário:

Evento	Transição	Descrição
Primeiro épico ou ticket criado	`draft` → `planning`	Especificação entra no corredor de planejamento
Planning review passou	corredor → `ready`	Especificação liberada para implementação
Todos tickets alcançam `done`	`in_progress` → `ready_for_review`	Disparado quando o último ticket completa
Todos tickets done (review desabilitado)	`in_progress` → `completed`	Quando `requireImplementationReview` é `false`

Estados Protegidos

Uma vez que uma especificação alcança ready, ela não regride automaticamente para um estado de planejamento. Esta proteção garante que planos validados permaneçam estáveis durante a implementação.

Para fazer mudanças estruturais em uma especificação ready, você deve explicitamente reabrir a sessão de planejamento — uma ação deliberada que reconhece que a especificação precisa de revalidação.

⚠️ Reabrir uma especificação após ready requer reopen_specification. Quaisquer work sessions em progresso devem ser completadas ou resetadas primeiro.

Veja Também

Estados do Ticket — Máquina de estados do ticket e regras de auto-cálculo
Ciclos de Vida — Os três ciclos que impulsionam essas transições
Gates de Qualidade — Os gates que disparam avanços de estado