@rse/ase 0.9.1 → 0.9.2

package/plugin/meta/ase-format-spec.md

@@ -7,11 +7,20 @@ Specification (SPEC)
 The **Artifact Set** **Specification (SPEC)** specifies the "input"
 and the "what" of the Software Engineering project.
 
-Each **Artifact** of the **Artifact Set** **Specification (SPEC)**
-is stored under `docs/spec/SPEC-<artifact-id/>-<artifact-slug/>.md`,
-relative to the project root directory, and with <artifact-slug/> being
-derived from <artifact-name/> (see below) by lower-casing and using `-`
-characters instead of spaces.
+Each **Artifact** of the **Artifact Set**
+**Specification (SPEC)** is stored under
+`docs/spec/SPEC-<artifact-no/>-<artifact-id/>-<artifact-slug/>.md`,
+relative to the project root directory, with <artifact-no/> being the
+zero-padded, two-digit sequence number of the **Artifact** (starting at
+`01`) according to the order of the **Artifact** list below, and with
+<artifact-slug/> being derived from <artifact-name/> (see below) by
+Pascal-casing each word (upper-casing its first letter) and using `-`
+characters instead of spaces (e.g. `Customer-Journey`).
+
+Each **Artifact** file *MUST* begin with a single blank line before its
+`#` heading and end with a single blank line after its last content line
+(followed by the trailing newline), mirroring the blank lines shown
+inside the `<format>` blocks below.
 
 Each **Artifact** contains two timestamps: the <timestamp-created/>
 is the timestamp when this **Artifact** was created. The
@@ -26,70 +35,207 @@ The **Artifact Set** **Specification (SPEC)** consists of the following
 distinct **Artifact**s (listed under their <artifact-name/> and their
 <artifact-id/>):
 
--   **Customer Journey (CJ)**:
-    The end-to-end experience a customer has while discovering, adopting,
-    and using the solution, mapping their steps, touchpoints, and emotions
-    over time.
-
--   **Solution Vision (SV)**:
+01. **Solution Vision (SV)**:
     The high-level, aspirational description of the solution, capturing
     its purpose, value proposition, and the desired future state it aims
     to achieve.
 
--   **Functional Requirements (FR)**:
+02. **Personas (PE)**:
+    The *archetypal* user profiles representing distinct user groups,
+    capturing their goals, needs, behaviors, and context.
+
+03. **Customer Journey (CJ)**:
+    The end-to-end experience a customer has while discovering, adopting,
+    and using the solution, mapping their steps, touchpoints, and emotions
+    over time.
+
+04. **Functional Requirements (FR)**:
     The concrete behaviors and capabilities the solution must provide,
     describing *what* the system does in terms of functions, features, and
     operations.
 
--   **Non-Functional Requirements (NR)**:
+05. **Non-Functional Requirements (NR)**:
     The quality attributes and constraints the solution must satisfy, such
     as performance, security, scalability, reliability, and usability.
 
--   **Data Model (DM)**:
+06. **Business Rules (BR)**:
+    The domain invariants, policies, and decision logic that must always
+    hold true in the problem domain, independent of any single feature,
+    constraining the Functional and Non-Functional Requirements.
+
+07. **Data Model (DM)**:
     The structure of named entities, named attributes, and named directed
     relationships (including a cardinality) of the data the solution
     manages, defining how information is organized and connected.
 
--   **Use Cases (UC)**:
-    The discrete goals users pursue with the solution, each describing an
-    actor's interaction to achieve a specific outcome.
+08. **State Model (SM)**:
+    For each entity with a non-trivial lifecycle, the legal states it can
+    occupy and the permitted transitions between them over its lifetime,
+    making the forbidden moves as explicit as the allowed ones.
 
--   **Use Case Scenarios (US)**:
-    The concrete step-by-step flows through a **Use Case**, detailing the
-    sequence of actions for main, alternative, and exceptional paths.
+09. **Glossary (GL)**:
+    The ubiquitous language of the domain, defining the meaning of each
+    domain term in business language, together with its synonyms and the
+    ambiguities to avoid, shared consistently across all Artifacts.
 
--   **Personas (PE)**:
-    The *archetypal* user profiles representing distinct user groups,
-    capturing their goals, needs, behaviors, and context.
+10. **Use Cases (UC)**:
+    The discrete goals users pursue with the solution, each describing
+    an actor's interaction to achieve a specific outcome. For each Use
+    Case, also the concrete step-by-step flows, detailing the sequence
+    of actions for main, alternative, and exceptional paths.
 
--   **Test Cases (TC)**:
+11. **Test Cases (TC)**:
     The verifiable conditions and steps used to confirm that requirements
     are correctly implemented, with mandatory defined inputs, mandatory
     expected outcomes, and optional pre- and post-conditions.
 
--   **Interaction Concept (IC)**:
+12. **Interaction Concept (IC)**:
     The overarching idea of how users interact with the solution,
     describing the intended workflows and interaction philosophy (e.g.
     auto-save behavior).
 
--   **Language Conventions (LC)**:
+13. **Language Conventions (LC)**:
     The terminology, naming, tone, and wording standards used consistently
     across the solution and its content.
 
--   **Dialog Patterns (DP)**:
+14. **Dialog Patterns (DP)**:
     The reusable interaction structures governing how the system and user
     exchange information across recurring conversational or UI flows (e.g.
     master-detail dialog).
 
--   **Dialog Storyboard (SB)**:
+15. **Dialog Storyboard (DS)**:
     The sequenced visual or textual depiction of a specific dialog flow,
     illustrating how an interaction unfolds screen by screen or turn by
     turn.
 
--   **Visual Design (VD)**:
+16. **Visual Design (VD)**:
     The aesthetic and layout aspects of the solution, defining colors,
     typography, spacing, imagery, and overall look and feel.
 
+The **Artifact**s have the following cross-references:
+
+```text
+SPEC-03-CJ Customer Journey  ──(step actor)─►     SPEC-02-PE Personas
+SPEC-06-BR Business Rules    ──(constrains)─►     SPEC-04-FR Functional Requirements
+SPEC-06-BR Business Rules    ──(constrains)─►     SPEC-05-NR Non-Functional Requirements
+SPEC-08-SM State Model       ──(of entity)─►      SPEC-07-DM Data Model
+SPEC-10-UC Use Cases         ──(use case actor)─► SPEC-02-PE Personas
+SPEC-10-UC Use Cases         ──(realizes)─►       SPEC-04-FR Functional Requirements
+SPEC-10-UC Use Cases         ──(transitions)─►    SPEC-08-SM State Model
+SPEC-11-TC Test Cases        ──(verifies)─►       SPEC-04-FR Functional Requirements
+SPEC-11-TC Test Cases        ──(verifies)─►       SPEC-05-NR Non-Functional Requirements
+SPEC-15-DS Dialog Storyboard ──(scenario)─►       SPEC-10-UC Use Cases
+SPEC-15-DS Dialog Storyboard ──(pattern)─►        SPEC-14-DP Dialog Patterns
+```
+
+Solution Vision (SV)
+--------------------
+
+The high-level, aspirational description of the solution, capturing
+its purpose, value proposition, and the desired future state it aims
+to achieve.
+
+-   Format:
+
+    <format>
+
+    #   SPECIFICATION: SOLUTION VISION (SPEC-SV)
+
+    ✳   Created:  **<timestamp-created/>**
+    ✎   Modified: **<timestamp-modified/>**
+
+    <spec-sv-aspect/>
+    <spec-sv-aspect/>
+    [...]
+
+    </format>
+
+-   <spec-sv-aspect/> format:
+
+    <format>
+
+    ##  ASPECT: <spec-sv-aspect-name/> <a id="SPEC-SV-<spec-sv-aspect-id/>"></a>
+
+    <spec-sv-aspect-statement/>
+
+    </format>
+
+-   <spec-sv-aspect/> details:
+
+    -   <spec-sv-aspect-id/>: per-artifact unique "slug" of always 1-3
+        lower-cased words (concatenated with "-" characters and
+        in total not longer than 30 characters), derived from
+        <spec-sv-aspect-name/>.
+
+    -   <spec-sv-aspect-name/>: a short (2-5 word) summary of the vision
+        aspect. The recommended aspects are `Purpose` (why the solution
+        exists), `Target Audience` (who it serves), `Value Proposition`
+        (the unique benefit offered), `Differentiators` (how it stands
+        apart from alternatives), and `Future State` (the desired
+        outcome once adopted).
+
+    -   <spec-sv-aspect-statement/>: a concise paragraph (1-3 sentences)
+        of prose describing the vision aspect in an aspirational but
+        unambiguous tone.
+
+Personas (PE)
+-------------
+
+The *archetypal* user profiles representing distinct user groups,
+capturing their goals, needs, behaviors, and context.
+
+-   Format:
+
+    <format>
+
+    #   SPECIFICATION: PERSONAS (SPEC-PE)
+
+    ✳   Created:  **<timestamp-created/>**
+    ✎   Modified: **<timestamp-modified/>**
+
+    <spec-pe-persona/>
+    <spec-pe-persona/>
+    [...]
+
+    </format>
+
+-   <spec-pe-persona/> format:
+
+    <format>
+
+    ##  PERSONA: <spec-pe-persona-name/> <a id="SPEC-PE-<spec-pe-persona-id/>"></a>
+
+    -   Gender: <spec-pe-persona-gender/>
+    -   Age:    <spec-pe-persona-age/>
+    -   Role:   <spec-pe-persona-role/>
+
+    "<spec-pe-persona-quote/>"
+
+    </format>
+
+-   <spec-pe-persona/> details:
+
+    -   <spec-pe-persona-id/>: per-artifact unique "slug" of always 1-3
+        lower-cased words (concatenated with "-" characters and
+        in total not longer than 30 characters), derived from
+        <spec-pe-persona-name/>.
+
+    -   <spec-pe-persona-name/>: per-artifact unique first name of fictional
+        described person.
+
+    -   <spec-pe-persona-gender/>: the gender of the persona: `male`,
+        `female`, or `diverse`.
+
+    -   <spec-pe-persona-age/>: the age in years of the persona.
+
+    -   <spec-pe-persona-role/>: the role of the persona.
+
+    -   <spec-pe-persona-quote/>: a short and bold, first-person statement —
+        written in the persona's own voice — that captures their core
+        attitude, motivation, frustration, or need in a single memorable line.
+        It's sometimes called the persona's "tagline," "mantra," or "defining
+        statement."
+
 Customer Journey (CJ)
 ---------------------
 
@@ -116,7 +262,7 @@ over time.
 
     <format>
 
-    ##  STEP SPEC-CJ-<spec-cj-step-id/>: <spec-cj-step-name/>
+    ##  STEP: <spec-cj-step-name/> <a id="SPEC-CJ-<spec-cj-step-id/>"></a>
 
     -   Stage:      <spec-cj-step-stage/>
     -   Actor:      <spec-cj-step-actor/>
@@ -166,56 +312,6 @@ over time.
     -   In case a <spec-cj-step/> has no pain point at all, the
         entire `- Pain Point:` bullet point is omitted.
 
-Solution Vision (SV)
---------------------
-
-The high-level, aspirational description of the solution, capturing
-its purpose, value proposition, and the desired future state it aims
-to achieve.
-
--   Format:
-
-    <format>
-
-    #   SPECIFICATION: SOLUTION VISION (SPEC-SV)
-
-    ✳   Created:  **<timestamp-created/>**
-    ✎   Modified: **<timestamp-modified/>**
-
-    <spec-sv-aspect/>
-    <spec-sv-aspect/>
-    [...]
-
-    </format>
-
--   <spec-sv-aspect/> format:
-
-    <format>
-
-    ##  ASPECT SPEC-SV-<spec-sv-aspect-id/>: <spec-sv-aspect-name/>
-
-    <spec-sv-aspect-statement/>
-
-    </format>
-
--   <spec-sv-aspect/> details:
-
-    -   <spec-sv-aspect-id/>: per-artifact unique "slug" of always 1-3
-        lower-cased words (concatenated with "-" characters and
-        in total not longer than 30 characters), derived from
-        <spec-sv-aspect-name/>.
-
-    -   <spec-sv-aspect-name/>: a short (2-5 word) summary of the vision
-        aspect. The recommended aspects are `Purpose` (why the solution
-        exists), `Target Audience` (who it serves), `Value Proposition`
-        (the unique benefit offered), `Differentiators` (how it stands
-        apart from alternatives), and `Future State` (the desired
-        outcome once adopted).
-
-    -   <spec-sv-aspect-statement/>: a concise paragraph (1-3 sentences)
-        of prose describing the vision aspect in an aspirational but
-        unambiguous tone.
-
 Functional Requirements (FR)
 ----------------------------
 
@@ -242,12 +338,12 @@ operations.
 
     <format>
 
-    ##  REQUIREMENT SPEC-FR-<spec-fr-requirement-id/>: <spec-fr-requirement-name/>
+    ##  REQUIREMENT: <spec-fr-requirement-name/> <a id="SPEC-FR-<spec-fr-requirement-id/>"></a>
 
     -   Priority: <spec-fr-requirement-priority/>
 
-    <spec-fr-requirement-statement/>
-    (why: <spec-fr-requirement-rationale/>)
+    <spec-fr-requirement-statement/>,
+    **BECAUSE** <spec-fr-requirement-rationale/>.
 
     </format>
 
@@ -262,18 +358,21 @@ operations.
         functional requirement.
 
     -   <spec-fr-requirement-priority/>: the MoSCoW priority of the
-        requirement: `MUST`, `SHOULD`, `COULD`, or `WONT`.
+        requirement: `MUST`, `SHOULD`, `COULD`, or `WONT`. The `WONT`
+        priority records a requirement deliberately excluded from the
+        current scope ("won't have this time"), preserving the conscious
+        decision rather than silently dropping it.
 
     -   <spec-fr-requirement-statement/>: a concise paragraph (1-3
         sentences) of prose describing *what* the solution must do,
-        written with the keyword `MUST`, `SHOULD`, `COULD`, or `WILL
-        NOT` to indicate the obligation level.
+        written with the keyword `MUST`, `SHOULD`, `COULD`, or `WONT`
+        to indicate the obligation level.
 
     -   <spec-fr-requirement-rationale/>: the 1-sentence rationale ("why")
         of the functional requirement.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Non-Functional Requirements (NR)
 --------------------------------
@@ -300,14 +399,13 @@ as performance, security, scalability, reliability, and usability.
 
     <format>
 
-    ##  REQUIREMENT SPEC-NR-<spec-nr-requirement-id/>: <spec-nr-requirement-name/>
+    ##  REQUIREMENT: <spec-nr-requirement-name/> <a id="SPEC-NR-<spec-nr-requirement-id/>"></a>
 
-    -   Category: <spec-nr-requirement-category/>
     -   Priority: <spec-nr-requirement-priority/>
-    -   Metric:   <spec-nr-requirement-metric/>
+    -   Category: <spec-nr-requirement-category/>
 
-    <spec-nr-requirement-statement/>
-    (why: <spec-nr-requirement-rationale/>)
+    <spec-nr-requirement-statement/>,
+    **BECAUSE** <spec-nr-requirement-rationale/>.
 
     </format>
 
@@ -321,28 +419,108 @@ as performance, security, scalability, reliability, and usability.
     -   <spec-nr-requirement-name/>: a short (3-8 word) summary of the
         non-functional requirement.
 
-    -   <spec-nr-requirement-category/>: the quality attribute category
-        the requirement addresses, one of `Performance`, `Scalability`,
-        `Reliability`, `Availability`, `Security`, `Privacy`,
-        `Usability`, `Accessibility`, `Maintainability`, `Portability`,
-        `Compatibility`, or `Compliance`.
-
     -   <spec-nr-requirement-priority/>: the MoSCoW priority of the
-        requirement: `MUST`, `SHOULD`, `COULD`, or `WONT`.
+        requirement: `MUST`, `SHOULD`, `COULD`, or `WONT`. The `WONT`
+        priority records a requirement deliberately excluded from the
+        current scope ("won't have this time"), preserving the conscious
+        decision rather than silently dropping it.
 
-    -   <spec-nr-requirement-metric/>: the measurable, verifiable
-        threshold or target by which the requirement is judged satisfied
-        (e.g. `p95 latency < 200ms`, `99.9% uptime`).
+    -   <spec-nr-requirement-category/>: the quality attribute category
+        the requirement addresses, one of `Performance`,
+        `Compatibility`, `Usability`, `Reliability`, `Security`,
+        `Safety`, `Maintainability`, `Flexibility`, and `Compliance`,
+        according to the top-level characteristics in the ISO/IEC
+        25010:2023 Software-Quality Model (except for `Functional
+        Suitability` which is described by our Functional Requirements
+        (FR)).
 
     -   <spec-nr-requirement-statement/>: a concise paragraph (1-3
         sentences) of prose describing the quality attribute or
-        constraint the solution must satisfy.
+        constraint the solution must satisfy. It especially *MUST*
+        contain a *METRIC* within the <spec-nr-requirement-category/>,
+        which (according to the SMART principle) is the *specific*,
+        *measurable*, *achievable*, *relevant* and *time-bound*
+        threshold or target by which the requirement is judged satisfied
+        (e.g. `p95 latency < 200ms`, `99.9% uptime`).
 
     -   <spec-nr-requirement-rationale/>: the 1-sentence rationale ("why")
         of the non-functional requirement.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
+
+Business Rules (BR)
+-------------------
+
+The domain invariants, policies, and decision logic that must always
+hold true in the problem domain, independent of any single feature,
+constraining the Functional and Non-Functional Requirements.
+
+-   Format:
+
+    <format>
+
+    #   SPECIFICATION: BUSINESS RULES (SPEC-BR)
+
+    ✳   Created:  **<timestamp-created/>**
+    ✎   Modified: **<timestamp-modified/>**
+
+    <spec-br-rule/>
+    <spec-br-rule/>
+    [...]
+
+    </format>
+
+-   <spec-br-rule/> format:
+
+    <format>
+
+    ##  RULE: <spec-br-rule-name/> <a id="SPEC-BR-<spec-br-rule-id/>"></a>
+
+    -   Category:   <spec-br-rule-category/>
+    -   Constrains: <spec-br-rule-constrains/>
+
+    <spec-br-rule-statement/>,
+    **BECAUSE** <spec-br-rule-rationale/>.
+
+    </format>
+
+-   <spec-br-rule/> details:
+
+    -   <spec-br-rule-id/>: per-artifact unique "slug" of always 1-3
+        lower-cased words (concatenated with "-" characters and
+        in total not longer than 30 characters), derived from
+        <spec-br-rule-name/>.
+
+    -   <spec-br-rule-name/>: a short (3-8 word) summary of the business
+        rule.
+
+    -   <spec-br-rule-category/>: the kind of rule, one of `Invariant`
+        (a condition that must always hold), `Constraint` (a limit on
+        allowed values or actions), `Derivation` (a value computed from
+        others), or `Policy` (a deliberate business decision or
+        guideline).
+
+    -   <spec-br-rule-constrains/>: a comma-separated list of zero or more
+        `SPEC-FR-<spec-fr-requirement-id/>` or
+        `SPEC-NR-<spec-nr-requirement-id/>` references to the
+        corresponding **Aspect**s of the Functional or Non-Functional
+        Requirements **Artifact** the rule constrains.
+
+    -   <spec-br-rule-statement/>: a concise paragraph (1-3 sentences) of
+        prose stating the rule declaratively as a condition that must
+        hold, written with the keyword `MUST`, `SHOULD`, or `MUST NOT`
+        to indicate the obligation level, and naming the domain terms it
+        governs (defined in the Glossary **Artifact**).
+
+    -   <spec-br-rule-rationale/>: the 1-sentence rationale ("why") of the
+        business rule.
+
+    -   In case the rule constrains no specific requirement, the
+        entire `- Constrains:` bullet point is omitted.
+
+    -   In case the rationale is not present, the
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Data Model (DM)
 ---------------
@@ -370,24 +548,24 @@ manages, defining how information is organized and connected.
 
     <format>
 
-    ##  ENTITY SPEC-DM-<spec-dm-entity-id/>: <spec-dm-entity-name/>
+    ##  ENTITY: `<spec-dm-entity-name/>` <a id="SPEC-DM-<spec-dm-entity-id/>"></a>
 
-    <spec-dm-entity-description/>
-    (why: <spec-dm-entity-rationale/>)
+    <spec-dm-entity-description/>,
+    **BECAUSE** <spec-dm-entity-rationale/>.
 
     ### ATTRIBUTES
 
-    -   **<spec-dm-attribute-id/>**: <spec-dm-attribute-qualifier/><spec-dm-attribute-type/>:
-        <spec-dm-attribute-description/>
-        (why: <spec-dm-attribute-rationale/>)
+    -   `<spec-dm-attribute-id/>`: `<spec-dm-attribute-qualifier/><spec-dm-attribute-type/>`:<br/>
+        <spec-dm-attribute-description/>,
+        **BECAUSE** <spec-dm-attribute-rationale/>.
 
     -   [...]
 
     ### RELATIONS
 
-    -   **<spec-dm-relation-id/>**: <spec-dm-relation-target/>(<spec-dm-relation-cardinality/>):
-        <spec-dm-relation-description/>
-        (why: <spec-dm-relation-rationale/>)
+    -   `<spec-dm-relation-id/>`: [`<spec-dm-relation-target/>`](#<spec-dm-relation-id/>)(`<spec-dm-relation-cardinality/>`):<br/>
+        <spec-dm-relation-description/>,
+        **BECAUSE** <spec-dm-relation-rationale/>.
 
     -   [...]
 
@@ -437,6 +615,9 @@ manages, defining how information is organized and connected.
     -   <spec-dm-relation-target/>: the <spec-dm-entity-name/> of the
         entity the directed relation targets.
 
+    -   <spec-dm-relation-id/>: the <spec-dm-entity-id/> of the
+        entity the directed relation targets.
+
     -   <spec-dm-relation-cardinality/>: the cardinality of the entity
         relation at the target entity: `0..1` for zero or one
         ("optional"), `1` for exactly one ("mandatory"), `0..n` for
@@ -446,191 +627,276 @@ manages, defining how information is organized and connected.
         entire `### RELATIONS` block is omitted.
 
     -   In case any rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
-Use Cases (UC)
---------------
+State Model (SM)
+----------------
 
-The discrete goals users pursue with the solution, each describing an
-actor's interaction to achieve a specific outcome.
+For each entity with a non-trivial lifecycle, the legal states it can
+occupy and the permitted transitions between them over its lifetime,
+making the forbidden moves as explicit as the allowed ones.
 
 -   Format:
 
     <format>
 
-    #   SPECIFICATION: USE CASES (SPEC-UC)
+    #   SPECIFICATION: STATE MODEL (SPEC-SM)
 
     ✳   Created:  **<timestamp-created/>**
     ✎   Modified: **<timestamp-modified/>**
 
-    <spec-uc-usecase/>
-    <spec-uc-usecase/>
+    <spec-sm-lifecycle/>
+    <spec-sm-lifecycle/>
     [...]
 
     </format>
 
--   <spec-uc-usecase/> format:
+-   <spec-sm-lifecycle/> format:
 
     <format>
 
-    ##  USE CASE SPEC-UC-<spec-uc-usecase-id/>: <spec-uc-usecase-name/>
+    ##  LIFECYCLE: <spec-sm-lifecycle-name/> <a id="SPEC-SM-<spec-sm-lifecycle-id/>"></a>
 
-    -   Actor:        <spec-uc-usecase-actor/>
-    -   Goal:         <spec-uc-usecase-goal/>
-    -   Precondition: <spec-uc-usecase-precondition/>
-    -   Postcondition: <spec-uc-usecase-postcondition/>
+    -   Entity:  <spec-sm-lifecycle-entity/>
+    -   Initial: <spec-sm-lifecycle-initial/>
+    -   Final:   <spec-sm-lifecycle-final/>
 
-    <spec-uc-usecase-description/>
+    ### STATES
+
+    -   `<spec-sm-state-name/>`:
+        <spec-sm-state-description/>.
+
+    -   [...]
+
+    ### TRANSITIONS
+
+    -   `<spec-sm-transition-from/>` ─(<spec-sm-transition-event/>)─► `<spec-sm-transition-to/>`:
+        <spec-sm-transition-effect/>,
+        **WHEN** <spec-sm-transition-guard/>.
+
+    -   [...]
 
     </format>
 
--   <spec-uc-usecase/> details:
+-   <spec-sm-lifecycle/> details:
 
-    -   <spec-uc-usecase-id/>: per-artifact unique "slug" of always 1-3
+    -   <spec-sm-lifecycle-id/>: per-artifact unique "slug" of always 1-3
         lower-cased words (concatenated with "-" characters and
         in total not longer than 30 characters), derived from
-        <spec-uc-usecase-name/>.
+        <spec-sm-lifecycle-name/>.
 
-    -   <spec-uc-usecase-name/>: a short (3-8 word) summary of the use
-        case, phrased as an actor goal (e.g. `Reset Forgotten Password`).
+    -   <spec-sm-lifecycle-name/>: a short (1-3 word) name of the lifecycle,
+        normally the name of the entity it governs.
 
-    -   <spec-uc-usecase-actor/> is a `SPEC-PE-<spec-pe-persona-id/>`
-        reference to the corresponding **Aspect** of the Personas
-        **Artifact**, denoting the primary actor pursuing the goal.
+    -   <spec-sm-lifecycle-entity/> is a `SPEC-DM-<spec-dm-entity-id/>`
+        reference to the corresponding **Aspect** of the Data Model
+        **Artifact** whose lifecycle this models.
 
-    -   <spec-uc-usecase-goal/>: the 1-sentence statement of what the
-        actor wants to achieve through this use case.
+    -   <spec-sm-lifecycle-initial/>: the <spec-sm-state-name/> of the
+        single state every instance of the entity enters upon creation.
 
-    -   <spec-uc-usecase-precondition/>: the condition that must hold
-        before the use case can begin.
+    -   <spec-sm-lifecycle-final/>: a comma-separated list of one or more
+        <spec-sm-state-name/>s in which the entity may legally come to
+        rest permanently (terminal states).
 
-    -   <spec-uc-usecase-postcondition/>: the condition that holds after
-        the use case completes successfully.
+    -   <spec-sm-state-name/>: a short, Pascal-cased, per-lifecycle unique
+        name of one state the entity can occupy (e.g. `Draft`,
+        `Shipped`).
 
-    -   <spec-uc-usecase-description/>: a concise paragraph (1-3
-        sentences) of prose describing the use case at a glance, without
-        prescribing the step-by-step flow (which belongs to the **Use
-        Case Scenarios** **Artifact**).
+    -   <spec-sm-state-description/>: the 1-sentence description ("what
+        holds true") of the state.
 
-    -   In case a precondition or postcondition is not present, the
-        respective bullet point is omitted.
+    -   <spec-sm-transition-from/>: the <spec-sm-state-name/> the
+        transition departs from.
+
+    -   <spec-sm-transition-to/>: the <spec-sm-state-name/> the transition
+        arrives at.
+
+    -   <spec-sm-transition-event/>: a short, lower-cased verb naming the
+        event or action that triggers the transition (e.g. `submit`,
+        `ship`, `cancel`).
 
-Use Case Scenarios (US)
------------------------
+    -   <spec-sm-transition-effect/>: the 1-sentence description ("what
+        happens") of the side effect the transition produces.
 
-The concrete step-by-step flows through a **Use Case**, detailing the
-sequence of actions for main, alternative, and exceptional paths.
+    -   <spec-sm-transition-guard/>: the condition that must hold for the
+        transition to be permitted; any move not listed as a transition
+        is implicitly forbidden.
+
+    -   Every <spec-sm-state-name/> used in a transition *MUST* be
+        declared in the `### STATES` block, and every non-final state
+        *MUST* have at least one outgoing transition.
+
+    -   In case a transition has no side effect, the
+        entire `<spec-sm-transition-effect/>,` clause is omitted.
+
+    -   In case a transition has no guard, the
+        entire `, **WHEN** [...]` clause is omitted.
+
+Glossary (GL)
+-------------
+
+The ubiquitous language of the domain, defining the meaning of each
+domain term in business language, together with its synonyms and the
+ambiguities to avoid, shared consistently across all Artifacts.
 
 -   Format:
 
     <format>
 
-    #   SPECIFICATION: USE CASE SCENARIOS (SPEC-US)
+    #   SPECIFICATION: GLOSSARY (SPEC-GL)
 
     ✳   Created:  **<timestamp-created/>**
     ✎   Modified: **<timestamp-modified/>**
 
-    <spec-us-scenario/>
-    <spec-us-scenario/>
+    <spec-gl-term/>
+    <spec-gl-term/>
     [...]
 
     </format>
 
--   <spec-us-scenario/> format:
+-   <spec-gl-term/> format:
 
     <format>
 
-    ##  SCENARIO SPEC-US-<spec-us-scenario-id/>: <spec-us-scenario-name/>
+    ##  TERM: <spec-gl-term-name/> <a id="SPEC-GL-<spec-gl-term-id/>"></a>
 
-    -   Use Case: <spec-us-scenario-usecase/>
-    -   Type:     <spec-us-scenario-type/>
+    -   Synonyms: <spec-gl-term-synonyms/>
 
-    1.  <spec-us-scenario-step/>
-    2.  <spec-us-scenario-step/>
-    [...]
+    <spec-gl-term-definition/>
 
     </format>
 
--   <spec-us-scenario/> details:
+-   <spec-gl-term/> details:
 
-    -   <spec-us-scenario-id/>: per-artifact unique "slug" of always 1-3
+    -   <spec-gl-term-id/>: per-artifact unique "slug" of always 1-3
         lower-cased words (concatenated with "-" characters and
         in total not longer than 30 characters), derived from
-        <spec-us-scenario-name/>.
+        <spec-gl-term-name/>.
 
-    -   <spec-us-scenario-name/>: a short (3-8 word) summary of the
-        scenario.
+    -   <spec-gl-term-name/>: the canonical, preferred name of the domain
+        term, capitalized as it should appear in all Artifacts.
 
-    -   <spec-us-scenario-usecase/> is a `SPEC-UC-<spec-uc-usecase-id/>`
-        reference to the corresponding **Aspect** of the Use Cases
-        **Artifact** this scenario flows through.
+    -   <spec-gl-term-synonyms/>: a comma-separated list of one or more
+        alternative names or abbreviations that refer to the same term
+        but are *not* the preferred form.
 
-    -   <spec-us-scenario-type/>: the path the scenario represents, one
-        of `Main` (the primary, happy-path flow), `Alternative` (a
-        valid but secondary flow), or `Exceptional` (an error or
-        failure-handling flow).
+    -   <spec-gl-term-definition/>: a concise paragraph (1-3 sentences) of
+        prose defining the term in business language, independent of any
+        implementation, and referencing other terms by their
+        <spec-gl-term-name/> where helpful.
 
-    -   <spec-us-scenario-step/>: a single, imperative step in the flow,
-        naming the acting party (actor or system) and the action taken
-        (e.g. `The user submits the login form.`). Steps are numbered
-        sequentially to convey their order.
+    -   In case a term has no synonyms, the
+        entire `- Synonyms:` bullet point is omitted.
 
-Personas (PE)
--------------
+Use Cases (UC)
+--------------
 
-The *archetypal* user profiles representing distinct user groups,
-capturing their goals, needs, behaviors, and context.
+The discrete goals users pursue with the solution, each describing an
+actor's interaction to achieve a specific outcome. For each Use Case,
+also the concrete step-by-step flows, detailing the sequence of actions
+for main, alternative, and exceptional paths.
 
 -   Format:
 
     <format>
 
-    #   SPECIFICATION: PERSONAS (SPEC-PE)
+    #   SPECIFICATION: USE CASES (SPEC-UC)
 
     ✳   Created:  **<timestamp-created/>**
     ✎   Modified: **<timestamp-modified/>**
 
-    <spec-pe-persona/>
-    <spec-pe-persona/>
+    <spec-uc-usecase/>
+    <spec-uc-usecase/>
     [...]
 
     </format>
 
--   <spec-pe-persona/> format:
+-   <spec-uc-usecase/> format:
 
     <format>
 
-    ##  PERSONA SPEC-PE-<spec-pe-persona-id/>: <spec-pe-persona-name/>
+    ##  USE CASE: <spec-uc-usecase-name/> <a id="SPEC-UC-<spec-uc-usecase-id/>"></a>
 
-    -   Gender: <spec-pe-persona-gender/>
-    -   Age:    <spec-pe-persona-age/>
-    -   Role:   <spec-pe-persona-role/>
-    -   Quote:  "<spec-pe-persona-quote/>"
+    -   Actor:          <spec-uc-usecase-actor/>
+    -   Requirements:   <spec-uc-usecase-requirements/>
+    -   Goal:           <spec-uc-usecase-goal/>
+    -   Pre-Condition:  <spec-uc-usecase-precondition/>
+    -   Post-Condition: <spec-uc-usecase-postcondition/>
+
+    <spec-uc-usecase-description/>
+
+    <spec-uc-usecase-scenario/>
+    <spec-uc-usecase-scenario/>
+    [...]
 
     </format>
 
--   <spec-pe-persona/> details:
+-   <spec-uc-usecase/> details:
 
-    -   <spec-pe-persona-id/>: per-artifact unique "slug" of always 1-3
+    -   <spec-uc-usecase-id/>: per-artifact unique "slug" of always 1-3
         lower-cased words (concatenated with "-" characters and
         in total not longer than 30 characters), derived from
-        <spec-pe-persona-name/>.
+        <spec-uc-usecase-name/>.
 
-    -   <spec-pe-persona-name/>: per-artifact unique first name of fictional
-        described person.
+    -   <spec-uc-usecase-name/>: a short (3-8 word) summary of the use
+        case, phrased as an actor goal (e.g. `Reset Forgotten Password`).
 
-    -   <spec-pe-persona-gender/>: the gender of the persona: `male`,
-        `female`, or `diverse`.
+    -   <spec-uc-usecase-actor/> is a `SPEC-PE-<spec-pe-persona-id/>`
+        reference to the corresponding **Aspect** of the Personas
+        **Artifact**, denoting the primary actor pursuing the goal.
 
-    -   <spec-pe-persona-age/>: the age in years of the persona.
+    -   <spec-uc-usecase-requirements/> is a comma-separated list of one
+        or more `SPEC-FR-<spec-fr-requirement-id/>` references to the
+        corresponding **Aspect**s of the Functional Requirements
+        **Artifact** the use case realizes.
 
-    -   <spec-pe-persona-role/>: the role of the persona.
+    -   <spec-uc-usecase-goal/>: the 1-sentence statement of what the
+        actor wants to achieve through this use case.
 
-    -   <spec-pe-persona-quote/>: a short, first-person statement —
-        written in the persona's own voice — that captures their core
-        attitude, motivation, frustration, or need in a single memorable line.
-        It's sometimes called the persona's "tagline," "mantra," or "defining
-        statement."
+    -   <spec-uc-usecase-precondition/>: the condition that must hold
+        before the use case can begin.
+
+    -   <spec-uc-usecase-postcondition/>: the condition that holds after
+        the use case completes successfully.
+
+    -   <spec-uc-usecase-description/>: a concise paragraph (1-3
+        sentences) of prose describing the use case at a glance, without
+        prescribing the step-by-step flow (which belongs to the **Use
+        Case Scenarios** **Artifact**).
+
+    -   In case the use case realizes no specific functional requirement,
+        the entire `- Requirements:` bullet point is omitted.
+
+    -   In case a precondition or postcondition is not present, the
+        respective bullet point is omitted.
+
+-   <spec-uc-usecase-scenario/> format:
+
+    <format>
+
+    ### SCENARIO: <spec-uc-usecase-scenario-name/> (<spec-uc-usecase-scenario-type/>)
+
+    1.  <spec-uc-usecase-scenario-step/>
+    2.  <spec-uc-usecase-scenario-step/>
+    [...]
+
+    </format>
+
+-   <spec-uc-usecase-scenario/> details:
+
+    -   <spec-uc-usecase-scenario-name/>: a short (3-8 word) summary of the
+        scenario.
+
+    -   <spec-uc-usecase-scenario-type/>: the path the scenario represents, one
+        of `Main` (the primary, happy-path flow), `Alternative` (a
+        valid but secondary flow), or `Exceptional` (an error or
+        failure-handling flow).
+
+    -   <spec-uc-usecase-scenario-step/>: a single, imperative step in the flow,
+        naming the acting party (actor or system) and the action taken
+        (e.g. `The user submits the login form.`). Steps are numbered
+        sequentially to convey their order.
 
 Test Cases (TC)
 ---------------
@@ -658,13 +924,13 @@ expected outcomes, and optional pre- and post-conditions.
 
     <format>
 
-    ##  TEST CASE SPEC-TC-<spec-tc-testcase-id/>: <spec-tc-testcase-name/>
+    ##  TEST CASE: <spec-tc-testcase-name/> <a id="SPEC-TC-<spec-tc-testcase-id/>"></a>
 
-    -   Verifies:      <spec-tc-testcase-verifies/>
-    -   Precondition:  <spec-tc-testcase-precondition/>
-    -   Input:         <spec-tc-testcase-input/>
-    -   Expected:      <spec-tc-testcase-expected/>
-    -   Postcondition: <spec-tc-testcase-postcondition/>
+    -   Verifies:       <spec-tc-testcase-verifies/>
+    -   Pre-Condition:  <spec-tc-testcase-precondition/>
+    -   Input:          <spec-tc-testcase-input/>
+    -   Expected:       <spec-tc-testcase-expected/>
+    -   Post-Condition: <spec-tc-testcase-postcondition/>
 
     </format>
 
@@ -695,7 +961,7 @@ expected outcomes, and optional pre- and post-conditions.
     -   <spec-tc-testcase-postcondition/>: the state that must hold after
         the test completes (optional).
 
-    -   In case a precondition or postcondition is not present, the
+    -   In case a pre-condition or post-condition is not present, the
         respective bullet point is omitted.
 
 Interaction Concept (IC)
@@ -724,10 +990,10 @@ auto-save behavior).
 
     <format>
 
-    ##  PRINCIPLE SPEC-IC-<spec-ic-principle-id/>: <spec-ic-principle-name/>
+    ##  PRINCIPLE: <spec-ic-principle-name/> <a id="SPEC-IC-<spec-ic-principle-id/>"></a>
 
-    <spec-ic-principle-statement/>
-    (why: <spec-ic-principle-rationale/>)
+    <spec-ic-principle-statement/>,
+    **BECAUSE** <spec-ic-principle-rationale/>.
 
     </format>
 
@@ -750,7 +1016,7 @@ auto-save behavior).
         of the interaction principle.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Language Conventions (LC)
 -------------------------
@@ -777,7 +1043,7 @@ across the solution and its content.
 
     <format>
 
-    ##  CONVENTION SPEC-LC-<spec-lc-convention-id/>: <spec-lc-convention-name/>
+    ##  CONVENTION: <spec-lc-convention-name/> <a id="SPEC-LC-<spec-lc-convention-id/>"></a>
 
     -   Category: <spec-lc-convention-category/>
 
@@ -837,12 +1103,13 @@ master-detail dialog).
 
     <format>
 
-    ##  PATTERN SPEC-DP-<spec-dp-pattern-id/>: <spec-dp-pattern-name/>
+    ##  PATTERN: <spec-dp-pattern-name/> <a id="SPEC-DP-<spec-dp-pattern-id/>"></a>
 
     -   Context: <spec-dp-pattern-context/>
+    -   Problem: <spec-dp-pattern-problem/>
 
-    <spec-dp-pattern-description/>
-    (why: <spec-dp-pattern-rationale/>)
+    <spec-dp-pattern-description/>,
+    **BECAUSE** <spec-dp-pattern-rationale/>.
 
     </format>
 
@@ -859,17 +1126,27 @@ master-detail dialog).
     -   <spec-dp-pattern-context/>: the recurring situation or flow in
         which the pattern is applied.
 
+    -   <spec-dp-pattern-problem/>: the 1-sentence tension or difficulty
+        the pattern resolves ("why is the pattern needed"),
+        stated independently of its solution (which belongs to
+        <spec-dp-pattern-description/>) and its rationale (which belongs
+        to <spec-dp-pattern-rationale/>).
+
     -   <spec-dp-pattern-description/>: a concise paragraph (1-3
         sentences) of prose describing the reusable interaction structure
         and how the system and user exchange information within it.
 
-    -   <spec-dp-pattern-rationale/>: the 1-sentence rationale ("why") of
-        the dialog pattern.
+    -   <spec-dp-pattern-rationale/>: the 1-sentence justification for why
+        the structure in <spec-dp-pattern-description/> is the right
+        response — the benefit it secures or the trade-off it wins.
+        Unlike <spec-dp-pattern-problem/> (which states *why the pattern
+        is needed*, independent of any solution), the rationale states
+        *why this particular solution is worth adopting*.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
-Dialog Storyboard (SB)
+Dialog Storyboard (DS)
 ----------------------
 
 The sequenced visual or textual depiction of a specific dialog flow,
@@ -880,59 +1157,66 @@ turn.
 
     <format>
 
-    #   SPECIFICATION: DIALOG STORYBOARD (SPEC-SB)
+    #   SPECIFICATION: DIALOG STORYBOARD (SPEC-DS)
 
     ✳   Created:  **<timestamp-created/>**
     ✎   Modified: **<timestamp-modified/>**
 
-    <spec-sb-storyboard/>
-    <spec-sb-storyboard/>
+    <spec-ds-storyboard/>
+    <spec-ds-storyboard/>
     [...]
 
     </format>
 
--   <spec-sb-storyboard/> format:
+-   <spec-ds-storyboard/> format:
 
     <format>
 
-    ##  STORYBOARD SPEC-SB-<spec-sb-storyboard-id/>: <spec-sb-storyboard-name/>
+    ##  STORYBOARD: <spec-ds-storyboard-name/> <a id="SPEC-DS-<spec-ds-storyboard-id/>"></a>
 
-    -   Pattern:  <spec-sb-storyboard-pattern/>
-    -   Scenario: <spec-sb-storyboard-scenario/>
+    -   Pattern:  <spec-ds-storyboard-pattern/>
+    -   Use Case: <spec-ds-storyboard-usecase/>
+    -   Scenario: <spec-ds-storyboard-scenario/>
 
-    1.  **<spec-sb-frame-name/>**: <spec-sb-frame-description/>
-    2.  **<spec-sb-frame-name/>**: <spec-sb-frame-description/>
+    1.  **<spec-ds-frame-name/>**: <spec-ds-frame-description/>
+    2.  **<spec-ds-frame-name/>**: <spec-ds-frame-description/>
     [...]
 
     </format>
 
--   <spec-sb-storyboard/> details:
+-   <spec-ds-storyboard/> details:
 
-    -   <spec-sb-storyboard-id/>: per-artifact unique "slug" of always
+    -   <spec-ds-storyboard-id/>: per-artifact unique "slug" of always
         1-3 lower-cased words (concatenated with "-" characters and
         in total not longer than 30 characters), derived from
-        <spec-sb-storyboard-name/>.
+        <spec-ds-storyboard-name/>.
 
-    -   <spec-sb-storyboard-name/>: a short (3-8 word) summary of the
+    -   <spec-ds-storyboard-name/>: a short (3-8 word) summary of the
         depicted dialog flow.
 
-    -   <spec-sb-storyboard-pattern/> is a `SPEC-DP-<spec-dp-pattern-id/>`
+    -   <spec-ds-storyboard-pattern/> is a `SPEC-DP-<spec-dp-pattern-id/>`
         reference to the corresponding **Aspect** of the Dialog Patterns
         **Artifact** the storyboard instantiates (optional).
 
-    -   <spec-sb-storyboard-scenario/> is a `SPEC-US-<spec-us-scenario-id/>`
-        reference to the corresponding **Aspect** of the Use Case
-        Scenarios **Artifact** the storyboard visualizes (optional).
+    -   <spec-ds-storyboard-usecase/> is a
+        `SPEC-UC-<spec-uc-usecase-id/>` reference to the corresponding
+        **Aspect** of the Use Case **Artifact** the storyboard
+        visualizes (optional).
 
-    -   <spec-sb-frame-name/>: a short (2-5 word) label for the screen,
+    -   <spec-ds-storyboard-scenario/> is a
+        Use Case scenario type `<spec-uc-usecase-scenario-type/>` of
+        the corresponding **Aspect** of the Use Case **Artifact** the
+        storyboard visualizes (optional).
+
+    -   <spec-ds-frame-name/>: a short (2-5 word) label for the screen,
         turn, or state depicted by the storyboard frame. Frames are
         numbered sequentially to convey their order.
 
-    -   <spec-sb-frame-description/>: a concise (1-2 sentence) description
+    -   <spec-ds-frame-description/>: a concise (1-2 sentence) description
         of what the user sees and does at this frame of the interaction.
 
-    -   In case a pattern or scenario reference is not present, the
-        respective bullet point is omitted.
+    -   In case a pattern, use case, or scenario reference is not present,
+        the respective bullet point is omitted.
 
 Visual Design (VD)
 ------------------
@@ -959,12 +1243,12 @@ typography, spacing, imagery, and overall look and feel.
 
     <format>
 
-    ##  ELEMENT SPEC-VD-<spec-vd-element-id/>: <spec-vd-element-name/>
+    ##  ELEMENT: <spec-vd-element-name/> <a id="SPEC-VD-<spec-vd-element-id/>"></a>
 
     -   Category: <spec-vd-element-category/>
 
-    <spec-vd-element-specification/>
-    (why: <spec-vd-element-rationale/>)
+    <spec-vd-element-specification/>,
+    **BECAUSE** <spec-vd-element-rationale/>.
 
     </format>
 
@@ -979,8 +1263,8 @@ typography, spacing, imagery, and overall look and feel.
         design element.
 
     -   <spec-vd-element-category/>: the aspect of visual design the
-        element governs, one of `Color`, `Typography`, `Spacing`,
-        `Layout`, `Iconography`, `Imagery`, `Motion`, or `Branding`.
+        element governs, one of `Color`, `Typography`, `Iconography`,
+        `Imagery`, `Layout`, or `Animation`.
 
     -   <spec-vd-element-specification/>: a concise paragraph (1-3
         sentences) of prose specifying the concrete values, tokens, or
@@ -991,4 +1275,4 @@ typography, spacing, imagery, and overall look and feel.
         the visual design element.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.