Task

A Task represents a concrete work item in a Scope's backlog — the implementation counterpart to UserStory requirements.

Tasks are classified by kind and priority, and track their progress through lifecycle_status. The on_hold flag marks a task as temporarily blocked without altering its lifecycle state. The related_acs field holds string references to the acceptance criteria the task addresses (e.g. "AC1.2"); these merge as a union across the scope hierarchy, following the same semantics as UserStory.tags.

Task carries both the Historized mixin (history: frozenset[HistoryEntry]) and the Commentable mixin (comments: frozenset[Comment]). Both fields accumulate across scope merges. See HistoryEntry and Comment.

Six kinds require an estimated_duration at instantiation time: enhancement, bug, documentation, release, deployment, and test. Omitting it for these kinds raises a validation error.

actual_duration records how long the task took overall, while active_duration records time actively spent working on it — the two can differ when the task involved background or automated processing. If only one is provided at instantiation, the other defaults to the same value.

links and risk_links hold typed relationships to other Tasks and to Risks respectively. See Links for the full concept, including the EXPLICIT/IMPLICIT provenance shared by every link kind.

TaskPriority

`TaskPriority`

Bases: str, Enum

Priority level of a Task.

TaskKind

`TaskKind`

Bases: str, Enum

Classifies the nature of a Task.

TaskLifecycleStatus

`TaskLifecycleStatus`

Bases: str, Enum

Lifecycle state of a Task.

Task

`Task`

Bases: MergeableModel, Historized, Commentable

A work item belonging to a Scope's backlog.

Attributes:

Name	Type	Description
`id`	`int`	Integer identifier, unique within the enclosing Scope's backlog.
`title`	`str`	Short free-text title summarising the work.
`description`	`str`	Full description containing all information needed to complete the task unambiguously.
`priority`	`TaskPriority`	Urgency level of the task.
`kind`	`TaskKind`	Nature of the work to be done.
`lifecycle_status`	`TaskLifecycleStatus`	Current position in the task lifecycle.
`on_hold`	`bool`	Whether the task is temporarily blocked from progressing. Defaults to `False`.
`estimated_duration`	`timedelta \| None`	Expected time to complete the task. Mandatory for kinds that require planning: enhancement, bug, documentation, release, deployment, and test. Defaults to `None`.
`actual_duration`	`timedelta \| None`	Time it actually took to complete the task. Defaults to `None`. If left unset while `active_duration` is provided, it mirrors `active_duration`.
`active_duration`	`timedelta \| None`	Time actively spent working on the task, which may differ from `actual_duration` when the task's elapsed time included background or automated processing. Defaults to `None`. If left unset while `actual_duration` is provided, it mirrors `actual_duration`.
`related_acs`	`frozenset[str]`	Set of acceptance criterion reference strings (e.g. `"AC1.2"`) that this task addresses. Defaults to an empty set.
`links`	`frozenset[TaskLink]`	Typed relationships to other Tasks. Defaults to an empty set.
`risk_links`	`frozenset[TaskRiskLink]`	Typed relationships to Risks affecting this task. Defaults to an empty set.

TaskLinkKind

`TaskLinkKind`

Bases: str, Enum

Classifies the nature of a relationship between two Tasks.

Attributes:

Name	Type	Description
`RELATES_TO`		A loose, non-directional association.
`DEPENDS_ON`		The owning Task cannot proceed until the target completes.
`DUPLICATES`		The owning Task describes the same work as the target.

TaskLink

`TaskLink`

Bases: BaseModel

A typed relationship from a Task to another Task.

Attributes:

Name	Type	Description
`target_task_id`	`int`	The id of the related Task.
`kind`	`TaskLinkKind`	The nature of the relationship.
`provenance`	`LinkProvenance`	Whether the relationship was explicitly asserted or implicitly inferred.

TaskRiskLink

`TaskRiskLink`

Bases: BaseModel

A typed relationship from a Task to a Risk it is affected by.

Attributes:

Name	Type	Description
`target_risk_id`	`int`	The id of the Risk affecting the owning Task.
`provenance`	`LinkProvenance`	Whether the relationship was explicitly asserted or implicitly inferred.