Domain Model

fushinryu-model is built around four entity types that form a containment hierarchy.

graph TD
    S[Scope] -->|contains| US[UserStory]
    S -->|backlog| T[Task]
    US -->|contains| AC[AcceptanceCriterion]
    AC -->|contains| V[ValidationEntry\nManualValidation · AutomatedValidation]
    T -. references .-> AC

Scope

A Scope is the top-level organisational unit. It groups related UserStory instances and Task work items under a named, identifiable container. Scopes can declare parent scopes, forming a directed acyclic graph (DAG) that supports inheritance — see Scope Hierarchy.

Key constraints

• id must follow programming identifier rules: start with a letter or _letter, followed by letters, digits, or underscores.
• User story id values must be unique within a scope.
• Task id values must be unique within the scope's backlog.
• description is optional free-form text; it is inherited from parent scopes when absent.

UserStory

A UserStory captures a high-level requirement from the perspective of a role using the classic As a / I want / so that structure, stored as who, what, and why fields.

Stories are classified as either functional or technical via the UserStoryType enum.

The optional dod field holds a free-form definition of done. The tags field is an unordered set of short label strings (frozenset[str]) used for categorisation; tags from parent and child stories are merged as a union.

Key constraints

• Acceptance criterion id values must be unique within a story.
• A story is considered validated (is_validated = True) only when it is active, has at least one active acceptance criterion, and all active criteria are validated.

Task

A Task represents a concrete work item assigned to a scope's backlog. It carries a title, a full description, a priority, a kind, and a lifecycle_status. The on_hold flag marks a task as temporarily blocked without changing its lifecycle state.

The related_acs field is a frozenset[str] of acceptance criterion references (e.g. "AC1.2") that the task addresses. It merges as a union across the scope hierarchy, the same way UserStory.tags does.

Key constraints

Field	Constraint
id	Integer, unique within the enclosing scope's backlog
estimated_duration	Required for enhancement, bug, documentation, release, deployment
related_acs	String references to AC ids; merged as a union

AcceptanceCriterion

An AcceptanceCriterion encodes the Given / When / Then structure of a testable condition.

Field	Required	Description
id	yes	Integer, unique within the enclosing story
then	yes	The expected outcome
given	no	Initial context or state
when	no	Trigger condition
tags	no	Unordered set of short label strings; merged as union
requirement_specification	no	ISO 29148 document type (SRS, SyRS, or StRS)
requirement_group	no	Requirement category within the specification

When both classification fields are provided, requirement_group must be valid for the chosen requirement_specification. Setting requirement_group without requirement_specification raises a validation error.

A criterion is validated (is_validated = True) when its validations set is non-empty and every record has passed=True.

ValidationEntry

Validation evidence is stored as a discriminated union of two frozen record types.

ManualValidation

Recorded by a human reviewer. Requires a verdict string explaining why the criterion passed or failed.

AutomatedValidation

Linked to an automated test or check. Identified by source (the file or module) and name (the test name). During merges, automated validations are deduplicated by (source, name), keeping the most recent timestamp.

The active flag

All three entity types carry an active: bool field (default True). Setting it to False performs a soft deletion — the entity is retained in the data but excluded from validation checks. An inactive UserStory implicitly deactivates all its acceptance criteria for validation purposes, regardless of their individual active values.