Estados do Ticket

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

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

Referência Rápida

pending --> ready --> active --> done

Estados

Regras de Auto-Cálculo

Os estados pending e ready 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 pending independente do status de dependência.

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.

Reset

Tickets completados podem ser resetados usando reset_work_session:

{
  "specificationId": "spec_xyz789",
  "ticketIds": ["tkt_abc123", "tkt_def456"]
}

Reset move tickets de done de volta para pending ou ready dependendo de se suas dependências ainda estão satisfeitas. Dados de work session (conclusões de passos, notas, resultados de critérios de aceite) são limpos. Commits e pull requests vinculados são preservados.

⚠️ Reset cascateia para baixo. Se o ticket B depende do ticket A e você reseta o ticket A, o ticket B também reverte para pending — mesmo se estava ready ou done. O grafo de dependência é sempre consistente.

Waves

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

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 ready_for_review — ou completed se o Implementation Review está desabilitado.

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