Ticket States

State machine reference for tickets — 5 states, auto-calculation rules, and transitions.

Tickets move through five states. Unlike specifications, ticket states are largely computed automatically based on dependencies and work session activity.

Ticket state machine: pending, ready, active, done, blocked with auto-calculation and cascade rules

Quick Reference

State	What it means	What happens next
`pending`	Has unresolved dependencies	Waits. Recalculates when dependencies complete.
`ready`	All dependencies satisfied, no blockers	Available for agents to pick up
`active`	Work session in progress	Agent is implementing
`done`	Work session completed with summary and validation	Dependent tickets recalculate
`blocked`	An external block was reported during a work session	Stays blocked until unblocked; then recalculates


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

States

State	Description
`pending`	The ticket exists but can’t be worked on yet. Has unresolved dependencies.
`ready`	All dependencies satisfied, no blockers. Work can begin.
`active`	A work session is in progress on this ticket.
`done`	Ticket is complete. Work session closed with summary and validation.
`blocked`	An external block was reported via `action_work_session`. First-class status — the ticket is not implementable until the block is cleared.

Auto-Calculation Rules

The pending, ready, and blocked states are computed automatically by SpecForge. You don’t set them directly. Calculation follows a precedence model:

1. External Block (Highest Precedence)

If a ticket has an external block reason reported via action_work_session with a blockReason, the ticket is forced to blocked regardless of dependency status. blocked is a first-class ticket status — it is not the same as pending.

2. Dependency Check

If any ticket in the dependsOn array is not in done status, the ticket stays pending. SpecForge evaluates all dependency links and requires every upstream ticket to be complete.

3. No Dependencies

If a ticket has no dependsOn links, it starts as ready immediately upon creation. These are your Wave 1 tickets — the first work that can begin.

4. All Dependencies Completed

If every ticket in the dependsOn array has reached done, the ticket transitions to ready. This recalculation happens automatically whenever an upstream ticket completes.

ℹ️ Status recalculation is immediate. The moment an upstream ticket reaches done, all its dependents are re-evaluated. Tickets whose last blocker was just resolved become ready instantly.

Manual Transitions

Two transitions require explicit action through MCP tools:

ready → active

Triggered by calling start_work_session with the ticket ID. The ticket must be in ready status.


{ "ticketId": "tkt_abc123" }

Opens a work session and transitions the ticket to active. Only one work session can be active per ticket at a time.

active → done

Triggered by calling complete_work_session with a summary and optional validation results.


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

Closes the work session and transitions the ticket to done. Dependent tickets recalculate immediately.

active → blocked

If an agent hits an external blocker mid-session, reporting it via action_work_session with a blockReason moves the ticket to blocked. When the block is cleared, the ticket recalculates to pending or ready based on its dependencies.

Waves

The dependency-based status calculation naturally produces waves of parallelizable work:

Wave	What it contains
Wave 1	Tickets with no dependencies — immediately `ready`
Wave 2	Tickets depending only on Wave 1 — become `ready` when Wave 1 completes
Wave 3	Tickets depending on Wave 1 or Wave 2 — and so on

Each wave is a batch of work that can execute in parallel with zero collision risk. The get_next_actionable_tickets tool returns the current wave of ready tickets, prioritized by importance and complexity.

Epic Auto-Completion

When every ticket within an epic reaches done, the epic is automatically marked as completed. No manual action required.

If the last epic in a specification completes (all tickets in all epics are done), the specification transitions to done.