Scope

A Scope is the top-level organisational unit that groups related UserStory instances. Scopes can declare ordered parent scopes to form a DAG inheritance hierarchy, which is flattened on demand via collapse().

The description field is optional free-form text summarising the scope's purpose. When a child scope omits it, the parent's description is inherited during merge.

See Scope Hierarchy for a detailed explanation of linearisation and the diamond-inheritance pattern.

Scope

Bases: MergeableModel

An organizational unit grouping related project artifacts.

Attributes:

Name	Type	Description
name	str	Human-readable display name for the scope.
id	str	Identifier following programming variable naming conventions: starts with a letter or underscore-then-letter, followed by letters, digits, or underscores.
description	str | None	A description of the scope's purpose. Defaults to None if unset.
user_stories	frozenset[UserStory]	The high-level requirements belonging to this scope. Each story's id must be unique within this scope.
backlog	frozenset[Task]	Work items assigned to this scope. Each task's id must be unique within this scope.
parents	tuple[Scope, ...]	Ordered parent scopes forming a directed acyclic graph. The first parent takes precedence over subsequent parents during collapse. Defaults to an empty sequence (no parents).

collapse()

Merges the full scope hierarchy into a single flat Scope.

Linearises the ancestor DAG using DFS pre-order with last-occurrence deduplication, then merges all scopes from lowest to highest precedence. The returned scope has no parents.

Returns:

Type	Description
Scope	A new Scope representing the effective merged scope.

Raises:

Type	Description
ValueError	If a cycle is detected in the parent graph.