Scope

A Scope is the top-level organisational unit that groups related UserStory instances, Task work items, and rule categories. 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.

The kind field classifies what type of organisational unit a scope represents. It accepts any ScopeKind member (organization, office, area, department, team, project, development) and defaults to None. Merge semantics follow the standard scalar rule: a child's non-None kind overrides the parent's; a None child kind leaves the parent's value intact.

The rule_categories field holds a frozenset[Category] of rule policy categories. Category names must be unique within the set. See Merging — Rule category merging for merge semantics and the Rule Categories reference for the Category, Ruleset, Commandment, and Suggestion types.

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.
roles	frozenset[Role]	Named actors belonging to this scope. Each role's name must be unique within this scope. Defaults to an empty frozenset.
role_assignments	frozenset[RoleAssignment]	Workforce assignments belonging to this scope. Each (employee.id, role.name) pair must be unique within this scope. Defaults to an empty frozenset.
procedures	frozenset[Procedure]	Documented procedures belonging to this scope. Each procedure's id must be unique within this scope. Procedures are non-mergeable: on merge, a child scope's procedure replaces a same-id parent procedure wholesale. Defaults to an empty frozenset.
risks	frozenset[Risk]	Project risks belonging to this scope. Each risk's id must be unique within this scope. Defaults to an empty frozenset.
kind	ScopeKind | None	Classifies the type of organizational unit this scope represents. Defaults to None if unset.
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.