fushinryu-model 0.1.0__tar.gz

fushinryu_model-0.1.0/.codegraph/.gitignore

@@ -0,0 +1,16 @@
+# CodeGraph data files
+# These are local to each machine and should not be committed
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Cache
+cache/
+
+# Logs
+*.log
+
+# Hook markers
+.dirty

fushinryu_model-0.1.0/.daimyo/rules/fushinryu_model/metadata.yml

@@ -0,0 +1,4 @@
+name: fushinryu_model
+description: Model of the Fushinryu development projects management methodology.
+parents:
+  - kencho

fushinryu_model-0.1.0/.daimyo/rules/fushinryu_model/tenka.yml

@@ -0,0 +1,229 @@
+tenka:
+  US50001:
+    who: developer
+    what: the generated project to meet its structural constraints
+    why: the project baseline is valid and ready to build upon
+    acs:
+      AC50001.1:
+        given: the generated project directory
+        when: examining its top-level structure
+        then: README.md and .gitignore are present
+      AC50001.2:
+        given: the generated project
+        when: examining the daimyo configuration
+        then: .daimyo/rules/<project_slug>/metadata.yml exists and is valid YAML
+      AC50001.3:
+        given: the generated project directory
+        when: examining its top-level structure
+        then: LICENSE.md is present and its content is non-empty
+      AC50001.4:
+        given: the generated project directory
+        when: reading pyproject.toml
+        then: it is valid TOML containing the rendered project name and version
+      AC50001.5:
+        given: the generated project directory
+        when: reading .project-metadata.yml
+        then: it is valid YAML declaring a daimyo scope keyed by the project slug
+
+  US50003:
+    who: developer
+    what: a well-structured Python module
+    why: the package is importable and typed from the first commit
+    acs:
+      AC50003.1:
+        given: the generated project directory
+        when: examining its top-level structure
+        then: a directory named after the module_name variable exists at the project root
+      AC50003.2:
+        given: the module directory
+        when: examining its contents
+        then: a py.typed marker file is present
+      AC50003.3:
+        given: the module directory
+        when: importing the module
+        then: the module is importable without errors
+
+  US50002:
+    active: false
+    who: developer
+    what: my first feature
+    why: I can deliver value incrementally
+    acs:
+      AC50002.1:
+        given: a new feature requirement
+        when: I begin implementation
+        then: "TODO — replace with a real acceptance criterion"
+
+  US1:
+    who: developer
+    what: define AcceptanceCriteria for UserStories
+    why: testable conditions for requirements can be specified
+    acs:
+      AC1.1:
+        then: an AcceptanceCriterion can be instantiated with only a mandatory then field
+      AC1.2:
+        given: an AcceptanceCriterion instantiated without explicit given or when values
+        then: given and when are None by default
+      AC1.3:
+        given: an AcceptanceCriterion instantiated without an explicit active value
+        then: active is True by default
+      AC1.4:
+        given: a parent and a child AcceptanceCriterion sharing the same id
+        when: they are merged
+        then: the child's non-None field values override the parent's
+      AC1.5:
+        given: a parent AcceptanceCriterion and a child AcceptanceCriterion with the same id and different active values
+        when: they are merged
+        then: the child's active value overrides the parent's
+
+  US2:
+    who: developer
+    what: define UserStories within a Scope
+    why: high-level needs can be described as structured requirements
+    acs:
+      AC2.1:
+        then: a UserStory can be instantiated with the required fields id, who, what, why, and type
+      AC2.2:
+        then: the type field is an enumeration accepting only functional and technical values
+      AC2.3:
+        given: a parent and a child UserStory sharing the same id
+        when: they are merged
+        then: the child's scalar field values override the parent's
+      AC2.4:
+        given: a parent and a child UserStory sharing the same id, each with an AcceptanceCriterion of the same id
+        when: they are merged
+        then: the overlapping AcceptanceCriteria are merged with the child's fields overriding the parent's
+      AC2.5:
+        given: a parent and a child UserStory sharing the same id, each with non-overlapping AcceptanceCriteria ids
+        when: they are merged
+        then: all AcceptanceCriteria from both UserStories are present in the result
+      AC2.6:
+        given: a UserStory instantiated without an explicit active value
+        then: active is True by default
+
+  US3:
+    who: developer
+    what: define Scopes as organizational units
+    why: project artifacts can be grouped and organized under a named unit
+    acs:
+      AC3.1:
+        then: a Scope can be instantiated with name, id, and description fields
+      AC3.2:
+        given: a Scope id that does not follow the identifier pattern (e.g., starts with a digit or contains spaces)
+        when: the Scope is instantiated
+        then: a validation error is raised
+      AC3.3:
+        given: a Scope id following the pattern starting with a letter or underscore-then-letter, followed by letters, digits, or underscores
+        when: the Scope is instantiated
+        then: the id is accepted without error
+      AC3.4:
+        given: a parent and a child Scope
+        when: they are merged
+        then: the child's scalar field values override the parent's
+      AC3.5:
+        given: a parent and a child Scope with non-overlapping UserStory ids
+        when: they are merged
+        then: all UserStories from both Scopes are present in the result
+      AC3.6:
+        given: a parent and a child Scope with a shared UserStory id
+        when: they are merged
+        then: the shared UserStory is merged with the child's scalar fields overriding the parent's, and their AcceptanceCriteria sets merged
+
+  US4:
+    who: developer
+    what: attach validation records to AcceptanceCriteria
+    why: fulfillment evidence can be stored and queried
+    acs:
+      AC4.1:
+        then: a ManualValidation can be instantiated with passed (defaults to False), timestamp, and verdict fields
+      AC4.2:
+        then: an AutomatedValidation can be instantiated with passed (defaults to False), timestamp, source, and name fields
+      AC4.3:
+        given: an AcceptanceCriterion instantiated without explicit validations
+        then: its validations collection is empty by default
+      AC4.4:
+        given: an AcceptanceCriterion with no validations
+        then: it is not considered validated
+      AC4.5:
+        given: an AcceptanceCriterion whose every validation has passed=True
+        then: it is considered validated
+      AC4.6:
+        given: an AcceptanceCriterion with at least one validation having passed=False
+        then: it is not considered validated
+      AC4.7:
+        given: a parent and child AcceptanceCriterion sharing the same id, each with ManualValidations
+        when: they are merged
+        then: all ManualValidations from both are present in the result
+      AC4.8:
+        given: a parent and child AcceptanceCriterion sharing the same id, each with an AutomatedValidation with the same source and name but different timestamps
+        when: they are merged
+        then: only the AutomatedValidation with the most recent timestamp is present in the result
+
+  US5:
+    who: developer
+    what: query whether a UserStory is fulfilled
+    why: sprint completion can be assessed
+    acs:
+      AC5.1:
+        given: a UserStory with no active AcceptanceCriteria
+        then: it is not considered validated
+      AC5.2:
+        given: a UserStory whose every active AcceptanceCriterion is validated
+        then: it is considered validated
+      AC5.3:
+        given: a UserStory with at least one active AcceptanceCriterion that is not validated
+        then: it is not considered validated
+      AC5.4:
+        given: an inactive UserStory (active=False)
+        when: querying whether it is fulfilled
+        then: it is not considered validated
+
+  US6:
+    who: developer
+    what: declare parent Scopes on a Scope
+    why: scopes can be organised into a directed acyclic graph hierarchy
+    acs:
+      AC6.1:
+        when: a Scope is instantiated without an explicit parents value
+        then: parents defaults to an empty sequence
+      AC6.2:
+        when: a Scope is instantiated with one or more parent Scope objects
+        then: the instance is created successfully
+      AC6.3:
+        given: a Scope instantiated with an ordered list of parents
+        when: examining parents
+        then: the order is preserved as declared
+      AC6.4:
+        given: a parent and a child Scope sharing the same id, each with a different parents value
+        when: they are merged
+        then: the child's parents value overrides the parent's
+
+  US7:
+    who: developer
+    what: collapse a Scope hierarchy into a single flat Scope
+    why: the merged effective scope can be obtained
+    acs:
+      AC7.1:
+        given: a Scope with no parents
+        when: it is collapsed
+        then: the result has equivalent fields and no parents
+      AC7.2:
+        given: a Scope with one parent
+        when: it is collapsed
+        then: the child's fields override the parent's fields
+      AC7.3:
+        given: a Scope with multiple ordered parents
+        when: it is collapsed
+        then: the first parent's fields override subsequent parents' fields
+      AC7.4:
+        given: a three-level hierarchy (grandparent, parent, child)
+        when: the child is collapsed
+        then: all merges are applied transitively
+      AC7.5:
+        given: a diamond DAG where two parents share a common ancestor
+        when: the child is collapsed
+        then: the common ancestor contributes exactly once at the lowest precedence
+      AC7.6:
+        given: a Scope hierarchy containing a cycle
+        when: collapse is called
+        then: a ValueError is raised

fushinryu_model-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Environment and secrets
+.env
+.env.*
+*.local
+
+# Coverage and test artifacts
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+tenka.fulfillment.yml

fushinryu_model-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://gitlab.com/Kencho1/pre-commit-sdlcgov-hooks
+    rev: v1.2.0
+    hooks:
+      - id: add-ai-assisted-trailer
+      - id: add-co-authored-by-ai-trailers
+      - id: enforce-ai-assisted-trailer
+      - id: enforce-co-authored-by-ai-trailer
+      - id: clean-commit-temp

fushinryu_model-0.1.0/.project-metadata.yml

@@ -0,0 +1,2 @@
+daimyo:
+  scope: fushinryu_model

fushinryu_model-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

fushinryu_model-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

fushinryu_model-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesús Alonso Abad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fushinryu_model-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: fushinryu-model
+Version: 0.1.0
+Summary: Model of the Fushinryu development projects management methodology.
+Project-URL: Repository, https://gitlab.com/Kencho1/fushinryu-model
+Project-URL: Documentation, https://fushinryu-model.readthedocs.io
+Author: Jesús Alonso Abad
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.11
+Requires-Dist: pleroma>=0.2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: mypy~=1.8; extra == 'test'
+Requires-Dist: pytest-cov~=6.0; extra == 'test'
+Requires-Dist: pytest-mark-ac~=1.1; extra == 'test'
+Requires-Dist: pytest~=8.3; extra == 'test'
+Requires-Dist: pyyaml~=6.0; extra == 'test'
+Requires-Dist: ruff~=0.8; extra == 'test'
+Requires-Dist: tox~=4.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# fushinryu-model
+
+Model of the Fūshinryū (風心流) development projects management methodology.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
+[![Documentation](https://readthedocs.org/projects/fushinryu-model/badge/?version=latest)](https://fushinryu-model.readthedocs.io)
+
+## Install
+
+```
+pip install fushinryu-model
+```
+
+## Quick example
+
+```python
+from datetime import datetime, timezone
+from fushinryu_model import AcceptanceCriterion, ManualValidation
+
+ac = AcceptanceCriterion(id=1, then="the system returns HTTP 200")
+validation = ManualValidation(verdict="verified manually", passed=True, timestamp=datetime.now(timezone.utc))
+ac = ac.model_copy(update={"validations": frozenset([validation])})
+assert ac.is_validated
+```
+
+Full documentation: <https://fushinryu-model.readthedocs.io>

fushinryu_model-0.1.0/README.md

@@ -0,0 +1,27 @@
+# fushinryu-model
+
+Model of the Fūshinryū (風心流) development projects management methodology.
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
+[![Documentation](https://readthedocs.org/projects/fushinryu-model/badge/?version=latest)](https://fushinryu-model.readthedocs.io)
+
+## Install
+
+```
+pip install fushinryu-model
+```
+
+## Quick example
+
+```python
+from datetime import datetime, timezone
+from fushinryu_model import AcceptanceCriterion, ManualValidation
+
+ac = AcceptanceCriterion(id=1, then="the system returns HTTP 200")
+validation = ManualValidation(verdict="verified manually", passed=True, timestamp=datetime.now(timezone.utc))
+ac = ac.model_copy(update={"validations": frozenset([validation])})
+assert ac.is_validated
+```
+
+Full documentation: <https://fushinryu-model.readthedocs.io>

fushinryu_model-0.1.0/docs/concepts/domain-model.md

@@ -0,0 +1,59 @@
+# Domain Model
+
+`fushinryu-model` is built around four entity types that form a containment hierarchy.
+
+```mermaid
+graph TD
+    S[Scope] -->|contains| US[UserStory]
+    US -->|contains| AC[AcceptanceCriterion]
+    AC -->|contains| V[ValidationEntry\nManualValidation · AutomatedValidation]
+```
+
+## Scope
+
+A `Scope` is the top-level organisational unit. It groups related `UserStory` instances under a named, identifiable container. Scopes can declare parent scopes, forming a directed acyclic graph (DAG) that supports inheritance — see [Scope Hierarchy](scope-hierarchy.md).
+
+**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.
+
+## 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.
+
+**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.
+
+## 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 |
+
+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.

fushinryu_model-0.1.0/docs/concepts/merging.md

@@ -0,0 +1,63 @@
+# Merging
+
+All domain entities — `Scope`, `UserStory`, and `AcceptanceCriterion` — inherit from `MergeableModel` (provided by the [`pleroma`](https://pypi.org/project/pleroma/) library). This gives them controlled merge semantics: a *child* entity overrides a *parent* entity field by field.
+
+## Scalar field merging
+
+For any simple field (`str`, `bool`, `int`, `Enum`), the child's value replaces the parent's:
+
+```python
+from fushinryu_model import AcceptanceCriterion
+
+parent = AcceptanceCriterion(id=1, given="a user is logged in", then="the dashboard is shown")
+child  = AcceptanceCriterion(id=1, given=None, then="the profile is shown")
+
+merged = AcceptanceCriterion.merge([parent, child])
+# merged.given == "a user is logged in"   ← parent kept (child was None)
+# merged.then  == "the profile is shown"  ← child wins
+```
+
+`None` values from the child do **not** override a non-`None` parent value unless `overwrite_none=True` is passed explicitly.
+
+## Collection merging with `merge_by_id`
+
+Collections of entities (acceptance criteria within a user story, user stories within a scope) are merged using the internal `merge_by_id` utility: entities are keyed by their integer `id`; overlapping ids are merged recursively; non-overlapping entities from both sets are included as-is.
+
+```python
+from fushinryu_model import AcceptanceCriterion, UserStory, UserStoryType
+
+parent_story = UserStory(
+    id=1, who="developer", what="X", why="Y", type=UserStoryType.FUNCTIONAL,
+    acceptance_criteria=frozenset([
+        AcceptanceCriterion(id=1, then="original condition"),
+        AcceptanceCriterion(id=2, then="only in parent"),
+    ]),
+)
+child_story = UserStory(
+    id=1, who="developer", what="X", why="Y", type=UserStoryType.FUNCTIONAL,
+    acceptance_criteria=frozenset([
+        AcceptanceCriterion(id=1, then="overridden condition"),  # same id → merged
+        AcceptanceCriterion(id=3, then="only in child"),          # new id → added
+    ]),
+)
+
+merged = UserStory.merge([parent_story, child_story])
+# AC id=1 → "overridden condition"
+# AC id=2 → "only in parent"
+# AC id=3 → "only in child"
+```
+
+## Validation record merging
+
+Validation records follow different rules depending on their type.
+
+| Type | Merge behaviour |
+|---|---|
+| `ManualValidation` | All records from both parent and child are **accumulated** |
+| `AutomatedValidation` | Deduplicated by `(source, name)`; the record with the **most recent timestamp** wins |
+
+This means manual review evidence is never discarded, while automated test results are automatically superseded by their latest run.
+
+## When merging is used
+
+Merging is the mechanism that powers [scope hierarchy collapse](scope-hierarchy.md). When `Scope.collapse()` is called, every scope in the ancestry is merged from lowest to highest precedence, producing a single flat scope with all inherited stories and criteria resolved.

fushinryu_model-0.1.0/docs/concepts/scope-hierarchy.md

@@ -0,0 +1,67 @@
+# Scope Hierarchy
+
+A `Scope` can declare an ordered list of **parent scopes** via its `parents` field. This forms a directed acyclic graph (DAG) that enables requirement inheritance: child scopes override parent definitions while still inheriting anything not explicitly changed.
+
+## Declaring parents
+
+```python
+from fushinryu_model import Scope
+
+base = Scope(id="base", name="Base", description="Shared requirements.")
+extended = Scope(id="extended", name="Extended", description="Extended requirements.", parents=(base,))
+```
+
+The `parents` tuple is **ordered**: the first parent takes precedence over subsequent parents when the hierarchy is collapsed.
+
+## Collapsing the hierarchy
+
+`Scope.collapse()` flattens the entire ancestry into a single `Scope` with no parents. The returned scope contains the merged result of every ancestor's user stories and acceptance criteria.
+
+```python
+flat = extended.collapse()
+# flat.parents == ()
+# flat.user_stories contains inherited and overriding stories merged
+```
+
+## Linearisation algorithm
+
+`collapse()` determines merge order using **DFS pre-order traversal with last-occurrence deduplication**:
+
+1. The root scope is visited first (highest precedence).
+2. Parents are visited in order; each scope's entire subtree is traversed before moving to the next sibling.
+3. If a scope appears more than once (shared ancestor — the *diamond pattern*), only its **last** occurrence in the traversal is kept.
+
+The result is a list ordered from highest to lowest merge precedence. Scopes are then merged from lowest to highest, so that higher-precedence scopes win.
+
+### Diamond example
+
+```
+        A (grandparent)
+       / \
+      B   C  (parents of D, in that order)
+       \ /
+        D (root)
+```
+
+```python
+A = Scope(id="a", name="A", description="Grandparent.")
+B = Scope(id="b", name="B", description="Parent B.", parents=(A,))
+C = Scope(id="c", name="C", description="Parent C.", parents=(A,))
+D = Scope(id="d", name="D", description="Root.", parents=(B, C))
+
+flat = D.collapse()
+# Linearisation order (highest → lowest precedence): D, B, C, A
+# A appears under both B and C but contributes only once, at the lowest precedence position.
+```
+
+Precedence order: **D > B > C > A**. B takes precedence over C because it is listed first in `D.parents`.
+
+## Cycle detection
+
+`collapse()` raises `ValueError` with a "Cycle detected" message if the parent graph contains a cycle. Cycles are invalid and cannot be collapsed.
+
+```python
+A = Scope(id="a", name="A", description=".")
+# Constructing a genuine cycle requires object mutation (not possible with frozen Pydantic models),
+# but the guard exists for programmatically constructed graphs.
+```