Checklist lifecycle.

A checklist moves through four states. Each state controls which actions your application can perform and when the answers become a stored result. The model exposes the transition methods directly.

The four states

pending -> in_progress -> completed -> reviewed
                ^             |
                +-------------+
                    reopen

pending means nobody has recorded a valid answer. The first answer moves the checklist to in_progress and stamps started_at.

completed means submit() passed all completion checks and stored the score, section rollups, pass result, completion time, and critical-failure flag.

reviewed adds a reviewer, review time, and optional outcome. The package does not define allowed outcome values.

Start only from a published version

$checklist = $version->start(
    subject: $vehicle,
    assignedTo: $driver,
    dueAt: now()->addDay(),
);

The subject, assignee, and due date are optional. Starting from a draft throws ChecklistStateException because the structure could still change.

The new checklist pins template_version_id. Publishing another version later does not change existing runs.

Assignment is not a state

$checklist->assign($driver);

Assignment updates the polymorphic assigned_to relation and dispatches ChecklistAssigned. It does not move a pending checklist into progress or reopen closed work.

Submission is the boundary

$unmet = $checklist->unmetRequirements();

if ($unmet === []) {
    $checklist->submit();
}

Submission is valid only from in_progress. It collects every unanswered required item and every unsatisfied conditional note or evidence requirement. When any remain, it throws IncompleteChecklistException with the full $unmet list and leaves the checklist open and unscored.

Review records an application outcome

$checklist->review($inspector, outcome: 'accepted');

Only a completed checklist can be reviewed. Review does not recalculate the score or change answers.

Reopening clears derived results

$checklist->reopen();

Completed and reviewed checklists can reopen. Reopening returns the checklist to in_progress, clears completion and review fields, and clears the stored score, pass decision, section scores, and critical-failure flag.

Existing responses and evidence remain. After corrections, another submit() recomputes results from the current applicable answers.

Invalid transitions throw

A pending checklist cannot submit or review. An in-progress checklist cannot review or reopen. Closed checklists reject answers, notes, evidence additions, and evidence removal until they reopen.

All lifecycle events implement ShouldDispatchAfterCommit. An outer transaction that rolls back does not announce work that was discarded.

What to read next

• Run a checklist for a task-focused execution guide.
• Answers and evidence for response correction and file behavior.
• Events and notifications for every transition payload.