Ticket States

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

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

Quick Reference

State	What it means	What happens next
`pending`	Has unresolved dependencies or an external block	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


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

States

State	Description
`pending`	The ticket exists but can’t be worked on. Has unresolved dependencies or an external block.
`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.

Auto-Calculation Rules

The pending and ready 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 pending regardless of dependency status.

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.

Reset

Completed tickets can be reset using reset_work_session:


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

Reset moves tickets from done back to pending or ready depending on whether their dependencies are still satisfied. Work session data (step completions, notes, acceptance criteria results) is cleared. Linked commits and pull requests are preserved.

⚠️ Resetting cascades downward. If ticket B depends on ticket A and you reset ticket A, ticket B also reverts to pending — even if it was ready or done. The dependency graph is always consistent.

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 ready_for_review — or completed if Implementation Review is disabled.