State Machines

State machines are kept small. When a workflow has its own meaningful lifecycle, it gets its own record rather than adding another Task status.

1. Task

BACKLOG → READY → WORKING ⇄ NEEDS_YOU
                     │
                     ▼
                   REVIEW ⇄ WORKING
                     │
                     ▼
                    DONE

Meaning

• BACKLOG: valid work, not yet ready to execute.
• READY: sufficiently specified and dependencies/other conditions allow starting when resources are available.
• WORKING: implementation is underway or Forge is completing work-related machinery.
• NEEDS_YOU: blocked on unresolved human judgement.
• REVIEW: there is a candidate revision awaiting quality/review decisions.
• DONE: human-approved completed work according to current policy.

Do not add PLANNING, AGENT_REVIEW, HUMAN_REVIEW, VERIFYING, or STARTING_AGENT as Task states.

2. Plan

DRAFT → IN_REVIEW
  ▲         │
  └─rejected┘
            │ approved
            ▼
         APPROVED

Plan revisions are immutable. Rejection normally returns the Plan identity to DRAFT while the next content is represented by a new Plan Revision.

Decomposition is an action/result associated with an approved Feature Plan, not a replacement terminal status for the Plan itself.

3. Review

PENDING → IN_PROGRESS → APPROVED
                 │
                 └────→ CHANGES_REQUESTED

Any nonterminal review can become STALE when the candidate revision changes.
An APPROVED review also cannot authorize a different revision.

The Task returns to WORKING when changes are requested.

4. Verification Run

QUEUED → RUNNING → PASSED
              ├──→ FAILED
              └──→ ERROR / CANCELLED

A verification result also has revision validity. “Stale” can be represented as a derived validity condition rather than mutating the historical run.

5. Agent Run

Do not collapse protocol state into only running/completed.

A practical initial model may include:

REQUESTED → STARTING → ACTIVE → STOPPING → STOPPED
                         │
                         └────→ WAITING (provider/decision semantics as metadata)

STOPPED requires a StoppedReason, for example:

• completed;
• user_stopped;
• crashed;
• supervisor_shutdown;
• agent_error;
• deferred.

Provider-specific result semantics determine the reason; raw process exit code alone is insufficient.

6. Agent Turn

REQUESTED → ACTIVE → COMPLETED
                 ├──→ INTERRUPTED
                 └──→ FAILED

Post-turn operations such as capturing the new Git revision can continue after COMPLETED. The Task should not enter Review until the required follow-up state is settled.

7. Operation

PENDING → RUNNING → SUCCEEDED
             │
             ├────→ FAILED → PENDING (explicit retry when safe)
             └────→ CANCELLED

Operation handlers must be written with retry/idempotency in mind. PENDING after restart is a normal recoverable state, not corruption.

8. Worktree

REQUESTED → PREPARING → READY → MERGING → MERGED
                       │        │
                       │        └── failure may return to READY
                       │
                       └────→ ABANDONED

READY / MERGED / ABANDONED → REMOVED only when cleanup safety checks pass.

The exact enum can be simplified during early implementation, but the lifecycle concept should remain separate from Task status.

9. Decision

OPEN → RESOLVED
  └──→ EXPIRED/DEFAULTED only when policy explicitly allows it

Destructive-action decisions never use automatic default firing.

10. Client sync

Connection and freshness are orthogonal:

Connection: DISCONNECTED | CONNECTING | CONNECTED
Sync:       HYDRATING | LIVE | STALE | DEGRADED

CONNECTED + STALE is a valid and important combination.