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().

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

Scope

Bases: MergeableModel

An organizational unit grouping related project artifacts.

Parameters:

Name	Type	Description	Default
name		Human-readable display name for the scope.	required
id		Identifier following programming variable naming conventions: starts with a letter or underscore-then-letter, followed by letters, digits, or underscores.	required
description		A description of the scope's purpose.	required
user_stories		The high-level requirements belonging to this scope. Each story's id must be unique within this scope.	required
parents		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).	required

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.