Task Lifecycle

Tasks in PREQSTATION have two dimensions:

Workflow status — where the card sits in the lifecycle
Run state — whether an agent has requested or claimed execution right now

That split is the main difference from the older in_progress / review model.

Workflow Model

workflow:   inbox  →  todo  →  ready  →  done
                       │         ▲
                       └─→ hold ─┘

run_state:  null | queued | working

Workflow Statuses

Status	Meaning	Typical next action
Inbox	New task, awaiting planning	Agent claims the task, reads local code, then runs `preq_plan_task()`
Todo	Planned and ready for implementation	Agent claims the task with `preq_start_task()` and begins work
Hold	Blocked or paused	Agent retries after resolving the blocker, or stays on hold
Ready	Implementation is complete and waiting for verification	Agent or owner runs verification and then `preq_review_task()`
Done	Verified and complete	Finished unless reopened manually
Archived	Hidden from active board views	Manual archival only

Run State Overlay

Run state is tracked independently from workflow status:

Run State	Meaning
`null`	No active execution claim
`queued`	Requested or dispatched, but not yet claimed by an agent
`working`	Claimed by an agent through `preq_start_task()`

OpenClaw or Telegram dispatch can mark a task as queued before an agent picks it up. preq_start_task() upgrades that to working.

Lifecycle Branches

Agents fetch the task once, resolve the current workflow status once, then execute exactly one matching branch.

From Inbox

preq_get_task(PROJ-284)         → status=inbox
preq_start_task(PROJ-284)       → run_state=working
read local code + write plan
preq_plan_task(PROJ-284, ...)   → status=todo, run_state=null
stop

From Todo

preq_get_task(PROJ-284)         → status=todo
preq_start_task(PROJ-284)       → run_state=working
implement + test + deploy
preq_complete_task(PROJ-284, ...) → status=ready, run_state=null
stop

From Hold

preq_get_task(PROJ-284)         → status=hold
preq_start_task(PROJ-284)       → run_state=working
investigate blocker / resume work
if resolved: preq_complete_task(PROJ-284, ...) → ready
if still blocked: preq_block_task(PROJ-284, ...) → hold
stop

From Ready

preq_get_task(PROJ-284)         → status=ready
preq_start_task(PROJ-284)       → run_state=working
run verification (tests, build, lint)
if passing: preq_review_task(PROJ-284) → done
if failing: preq_block_task(PROJ-284, ...) → hold
stop

Workflow Transitions

From	To	Trigger	Command
`inbox`	`todo`	Agent plan is uploaded	`preq_plan_task()`
`todo`	`ready`	Implementation is complete	`preq_complete_task()`
`hold`	`ready`	Blocker is resolved and work is complete	`preq_complete_task()`
`ready`	`done`	Verification succeeds	`preq_review_task()`
`inbox`	`hold`	Planning is blocked	`preq_block_task()`
`todo`	`hold`	Implementation is blocked	`preq_block_task()`
`hold`	`hold`	Blocker remains	`preq_block_task()`
`ready`	`hold`	Verification fails	`preq_block_task()`

preq_update_task_status() is the manual escape hatch for direct status changes such as reopening or archiving a card.

Result Payload

When an agent submits preq_complete_task(), it uploads a result object like:

{
  "summary": "Implemented JWT authentication. All tests passing.",
  "tests": "npm test",
  "pr_url": "https://github.com/project/pull/456",
  "notes": "Stored JWT in an httpOnly cookie.",
  "completed_at": "2026-03-12T14:22:00.000Z"
}

PREQSTATION stores that as a work log entry attached to the task.

Deployment Strategy

Task execution still respects the project deployment strategy:

Strategy	Behavior
`none`	No git operations. Code changes only.
`direct_commit`	Merge and push to the default branch.
`feature_branch`	Push the task branch and optionally create a PR.

Agents resolve the strategy through preq_get_project_settings() before deploy steps.