Estados do Ticket

Referência de máquina de estados para tickets — 5 estados, regras de auto-cálculo e transições.

Tickets se movem por cinco estados. Diferente de especificações, estados de tickets são amplamente computados automaticamente baseados em dependências e atividade de work session.

Máquina de estados do ticket: pending, ready, active, done, blocked com auto-cálculo e regras de cascata

Referência Rápida

Estado	O que significa	O que acontece a seguir
`pending`	Tem dependências não resolvidas	Aguarda. Recalcula quando dependências completam.
`ready`	Todas dependências satisfeitas, sem bloqueadores	Disponível para agentes pegarem
`active`	Work session em progresso	Agente está implementando
`done`	Work session completada com resumo e validação	Tickets dependentes recalculam
`blocked`	Um bloqueio externo foi reportado durante uma work session	Permanece bloqueado até ser desbloqueado; então recalcula


pending --> ready --> active --> done
                        |
                        v
                     blocked

Estados

Estado	Descrição
`pending`	O ticket existe mas não pode ser trabalhado ainda. Tem dependências não resolvidas.
`ready`	Todas dependências satisfeitas, sem bloqueadores. Trabalho pode começar.
`active`	Uma work session está em progresso neste ticket.
`done`	Ticket está completo. Work session fechada com resumo e validação.
`blocked`	Um bloqueio externo foi reportado via `action_work_session`. Status de primeira classe — o ticket não é implementável até o bloqueio ser removido.

Regras de Auto-Cálculo

Os estados pending, ready e blocked são computados automaticamente pelo SpecForge. Você não os define diretamente. O cálculo segue um modelo de precedência:

1. Bloqueio Externo (Precedência Mais Alta)

Se um ticket tem um motivo de bloqueio externo reportado via action_work_session com um blockReason, o ticket é forçado para blocked independente do status de dependência. blocked é um status de ticket de primeira classe — não é o mesmo que pending.

2. Verificação de Dependência

Se qualquer ticket no array dependsOn não está em status done, o ticket permanece pending. O SpecForge avalia todos os links de dependência e requer que todo ticket upstream esteja completo.

3. Sem Dependências

Se um ticket não tem links dependsOn, ele começa como ready imediatamente após a criação. Estes são seus tickets da Wave 1 — o primeiro trabalho que pode começar.

4. Todas Dependências Completadas

Se todo ticket no array dependsOn alcançou done, o ticket transiciona para ready. Este recálculo acontece automaticamente sempre que um ticket upstream completa.

ℹ️ O recálculo de status é imediato. No momento que um ticket upstream alcança done, todos seus dependentes são reavaliados. Tickets cujo último bloqueador acabou de ser resolvido se tornam ready instantaneamente.

Transições Manuais

Duas transições requerem ação explícita através de ferramentas MCP:

ready → active

Disparada chamando start_work_session com o ID do ticket. O ticket deve estar em status ready.


{ "ticketId": "tkt_abc123" }

Abre uma work session e transiciona o ticket para active. Apenas uma work session pode estar ativa por ticket por vez.

active → done

Disparada chamando complete_work_session com um resumo e resultados opcionais de validação.


{
  "ticketId": "tkt_abc123",
  "summary": "Implemented user registration endpoint with input validation and duplicate email detection.",
  "validation": {
    "tests": true,
    "lint": true,
    "typeCheck": true,
    "build": true
  }
}

Fecha a work session e transiciona o ticket para done. Tickets dependentes recalculam imediatamente.

active → blocked

Se um agente encontra um bloqueio externo no meio da sessão, reportá-lo via action_work_session com um blockReason move o ticket para blocked. Quando o bloqueio é removido, o ticket recalcula para pending ou ready baseado em suas dependências.

Waves

O cálculo de status baseado em dependência naturalmente produz waves de trabalho paralelizável:

Wave	O que contém
Wave 1	Tickets sem dependências — imediatamente `ready`
Wave 2	Tickets dependendo apenas da Wave 1 — se tornam `ready` quando a Wave 1 completa
Wave 3	Tickets dependendo da Wave 1 ou Wave 2 — e assim por diante

Cada wave é um lote de trabalho que pode executar em paralelo com zero risco de colisão. A ferramenta get_next_actionable_tickets retorna a wave atual de tickets ready, priorizados por importância e complexidade.

Auto-Conclusão do Épico

Quando todo ticket dentro de um épico alcança done, o épico é automaticamente marcado como completo. Nenhuma ação manual necessária.

Se o último épico em uma especificação completa (todos tickets em todos épicos estão done), a especificação transiciona para done.

Veja Também

Estados da Especificação — Máquina de estados da especificação
Sessões de Trabalho — Como sessões acionam transições de ticket
Épicos & Tickets — Modelo de dependência e estrutura do grafo