@rse/specbook 1.3.2 → 1.4.1

package/dst/specbook-format.yaml

@@ -93,7 +93,9 @@
 #
 #   -   All artifacts are optional, so that the schema can back not only
 #       a full specification but also the individual document types of
-#       the modeling coverage matrix above on their own.
+#       the modeling coverage matrix above on their own. Likewise, the
+#       properties and child objects of all artifacts are optional, so
+#       that a freshly initialized specification already lints cleanly.
 #
 #   -   The traditional hard Software Requirements Specification (SRS)
 #       vs. Architecture Description (AD) document split is
@@ -128,6 +130,7 @@
             optional: true
         -   name: TITLE
             desc: The title of the specification.
+            optional: true
         -   name: SUBTITLE
             desc: The subtitle of the specification.
             optional: true
@@ -182,17 +185,21 @@
         -   name: PURPOSE
             desc: >
                 Why the solution exists.
+            optional: true
         -   name: TARGET-AUDIENCE
             desc: >
                 Whom the solution serves.
+            optional: true
         -   name: SOLUTION
             desc: >
                 What the solution is, in a single sentence naming its kind or
                 category (e.g. a self-hosted, browser-based streaming platform).
+            optional: true
         -   name: VALUE-PROPOSITION
             desc: >
                 The benefit the solution offers its target audience, stated in
                 absolute terms without reference to alternatives.
+            optional: true
         -   name: DIFFERENTIATORS
             desc: >
                 How the solution stands apart from the alternatives, naming the
@@ -266,7 +273,9 @@
                 enforces itself is a Domain Rule or a Non-Functional Requirement instead) and
                 states a fact or event, not a decision (a deliberate exclusion is the `SCOPE` of
                 the Solution Vision or a `WONT` requirement instead).
+            optional: true
             format:
+                type: compact
                 maxTableColumns: 5
             props:
                 -   name: TYPE
@@ -340,7 +349,9 @@
                 (the `BROADER` term where one exists) and adds the characteristics delimiting the
                 term from its siblings (e.g. `A Message submitted by an Attendee as ...`), so that
                 the hierarchy and the definitions cross-check each other.
+            optional: true
             format:
+                type: compact
                 maxTableColumns: 5
             referenced:
                 -   "[[*]]"
@@ -352,8 +363,9 @@
                 labeled: true
                 qualified: true
                 config:
-                    size-node-width-max: 440
+                    size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: TYPE
                     desc: >
@@ -435,6 +447,7 @@
                 exactly this part and hold exactly the rights the Authorization Model grants to it
                 (plus those of the roles it `INHERITS`), while a persona holding several roles
                 holds the union of them.
+            optional: true
             format:
                 maxTableColumns: 5
             referenced:
@@ -479,6 +492,7 @@
                 persona's own voice, like a "tagline", "mantra", or "defining statement" -- that
                 captures their core attitude, motivation, frustration, or need in a single memorable
                 line. Non-user stakeholders are modeled as personas of type `Stakeholder`.
+            optional: true
             format:
                 maxTableColumns: 5
             props:
@@ -570,6 +584,7 @@
             desc: >
                 The end-to-end journey of a single persona (or of multiple personas sharing the same
                 experience as role variants), named with a 2-5 word summary of the pursued scenario.
+            optional: true
             props:
                 -   name: ACTORS
                     desc: >
@@ -657,10 +672,22 @@
                 event-driven (`When <trigger>, the system MUST ...`), state-driven (`While <state>,
                 the system MUST ...`), optional-feature (`Where <feature>, the system MUST ...`), or
                 unwanted-behavior (`If <condition>, then the system MUST ...`).
+            optional: true
             format:
                 maxTableColumns: 6
             referenced:
                 -   "[[USE-CASE:*]]"
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[FR.REQUIREMENT:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[RULE:*]],
+                    [[USE-CASE:*]], [[DM.ENTITY:*]], [[FV.COMPONENT:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: PRIORITY
                     desc: >
@@ -720,6 +747,7 @@
                 them (a `WONT` requirement, which the architecture rightly ignores, is the tolerated
                 exception the lint warning cannot tell apart) and its hub diagram shows what
                 answers it.
+            optional: true
             referenced:
                 -   "[[TACTIC:*]]"
                 -   "[[DECISION:*]]"
@@ -734,6 +762,7 @@
                 config:
                     size-node-width-max: 440
                     size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: PRIORITY
                     desc: >
@@ -823,10 +852,23 @@
                 <outcome>` item per case, applied in order with the first matching case winning,
                 and a closing sentence stating the outcome of the remaining cases ("otherwise")
                 and carrying the rationale.
+            optional: true
             format:
                 maxTableColumns: 5
             referenced:
                 -   "[[TEST-CASE:*]]"
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[RULE:*]], [[TERM:*]], [[FR.REQUIREMENT:*]], [[NR.REQUIREMENT:*]],
+                    [[PREMISE:*]], [[WORKFLOW:*]], [[HANDOFF:*]], [[USE-CASE:*]], [[TRANSITION:*]],
+                    [[PERMISSION:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: CATEGORY
                     desc: >
@@ -923,6 +965,7 @@
                 cases, a use case spans several activities, and an activity performed outside the
                 solution is covered by none at all -- so the workflow is no mere sequence of use
                 cases and cannot be assembled from them.
+            optional: true
             automaton:
                 nodes: ACTIVITY
                 edges: HANDOFF
@@ -1096,6 +1139,7 @@
                 relate it n:m to the Domain Workflow activities -- a use case spans several
                 activities and an activity is covered by several use cases -- so the two decompose
                 the same domain independently instead of nesting into each other.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -1268,6 +1312,7 @@
                 A named entity of the data model, carrying a Pascal-cased, 1-3 word long,
                 per-artifact unique name, and described by a 1-sentence description ("what") plus a
                 1-sentence rationale ("why").
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -1435,6 +1480,7 @@
                 state machine: exactly one initial state, at least one final state, every state
                 reachable from the initial state, and some final state reachable from every state
                 (a state from which no final state can be reached anymore is a livelock).
+            optional: true
             automaton:
                 nodes: STATE
                 edges: TRANSITION
@@ -1598,8 +1644,21 @@
                 they are granted, so that the permissions of all roles form the access matrix of
                 roles against entities. Any operation, state, or condition not covered by a
                 permission of the role (or of a role it `INHERITS`) is forbidden.
+            optional: true
             format:
+                type: compact
                 maxTableColumns: 8
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[PERMISSION:*]], [[ROLE:*]], [[DM.ENTITY:*]], [[STATE:*]], [[TRANSITION:*]],
+                    [[RULE:*]], [[USE-CASE:*]], [[SCENARIO:*]], [[ENDPOINT:*]], [[TEST-CASE:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: ROLE
                     desc: >
@@ -1699,6 +1758,7 @@
                 belongs to, where the kind-specific parts (HTTP method, GraphQL operation, topic
                 direction, command) are carried by the `OPERATION` and `LOCATOR` properties of the
                 endpoints only.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -1954,6 +2014,7 @@
                 Endpoints form a flat list: a hierarchy of sub-commands or sub-resources
                 is expressed by a path-style `LOCATOR` (e.g. `remote add`,
                 `/events/{eventId}/chat`) only.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -2187,13 +2248,16 @@
                 is a Dialog Pattern instead), decides between design alternatives (the alternative
                 it rejects is its `TRADE-OFF`), and is not verifiable by a metric (a measurable
                 quality bound is a Non-Functional Requirement instead).
+            optional: true
             referenced:
-                -   "[[PATTERN:*]]"
+                -   "[[DIALOG-PATTERN:*]]"
+            format:
+                type: compact
             diagram:
                 type: hub
                 center: self
                 nodes: "[[PRINCIPLE:*]], [[PERSONA:*]], [[STEP:*]], [[USE-CASE:*]], [[CONVENTION:*]],
-                    [[PATTERN:*]], [[ELEMENT:*]], [[DECISION:*]]"
+                    [[DIALOG-PATTERN:*]], [[ELEMENT:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -2284,6 +2348,19 @@
                 solution phrases what it says, not what it does (a behavior is an Interaction
                 Concept principle instead) and not what a term means (a definition is a Domain
                 Glossary term instead).
+            optional: true
+            format:
+                type: compact
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[CONVENTION:*]], [[PERSONA:*]], [[PRINCIPLE:*]], [[TERM:*]], [[DECISION:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: CATEGORY
                     desc: >
@@ -2338,7 +2415,7 @@
     optional: true
     diagram:
         type: grid
-        nodes: "[[PATTERN:*]]"
+        nodes: "[[DIALOG-PATTERN:*]]"
         properties:
             -   CATEGORY
         config:
@@ -2346,7 +2423,7 @@
             size-node-height-scale: 2
             grid-columns-max: 4
     children:
-        -   kind: PATTERN
+        -   kind: DIALOG-PATTERN
             desc: >
                 A single reusable dialog pattern, named with a short (2-5 word) summary (e.g.
                 `Master-Detail`, `Wizard`, `Inline Edit`) and described in a concise (1-3 sentence)
@@ -2357,10 +2434,11 @@
                 occurring in a single flow is a Dialog Storyboard frame instead) and is bound to a
                 particular kind of screen or flow (a solution-wide rule independent of any screen
                 is an Interaction Concept principle instead).
+            optional: true
             diagram:
                 type: hub
                 center: self
-                nodes: "[[PATTERN:*]], [[PRINCIPLE:*]], [[STORYBOARD:*]], [[DECISION:*]]"
+                nodes: "[[DIALOG-PATTERN:*]], [[PRINCIPLE:*]], [[STORYBOARD:*]], [[DECISION:*]]"
                 deep: true
                 labeled: true
                 qualified: true
@@ -2405,7 +2483,7 @@
                         pattern is composed of (e.g. a `Master-Detail` using an `Inline Edit` in
                         its detail), so that the patterns form a language of related structures
                         rather than a flat catalogue.
-                    value: list([[PATTERN:*]])
+                    value: list([[DIALOG-PATTERN:*]])
                     optional: true
                 -   name: TRADE-OFF
                     desc: >
@@ -2447,10 +2525,11 @@
                 one flow, as seen by its actors (the intent and the information exchanged are a Use
                 Cases scenario instead, and a structure recurring across flows is a Dialog Pattern
                 instead).
+            optional: true
             diagram:
                 type: hub
                 center: self
-                nodes: "[[STORYBOARD:*]], [[PERSONA:*]], [[SCENARIO:*]], [[PATTERN:*]], [[MOCKUP:*]]"
+                nodes: "[[STORYBOARD:*]], [[PERSONA:*]], [[SCENARIO:*]], [[DIALOG-PATTERN:*]], [[MOCKUP:*]]"
                 deep: true
                 labeled: true
                 qualified: true
@@ -2502,7 +2581,7 @@
                                 Comma-separated references to the DIALOG-PATTERNS objects the frame
                                 instantiates, so that a pattern is shown to recur across the
                                 concrete flows rather than merely being catalogued.
-                            value: list([[PATTERN:*]])
+                            value: list([[DIALOG-PATTERN:*]])
                             optional: true
                         -   name: SKETCH
                             desc: >
@@ -2558,7 +2637,9 @@
                 `MOCKUP` or a Dialog Storyboard frame instead), and is a decision rather than a
                 list of token values (the values are in the design system) or a measurable bound
                 (a bound is a Non-Functional Requirement instead).
+            optional: true
             format:
+                type: compact
                 maxTableColumns: 5
             diagram:
                 type: hub
@@ -2568,6 +2649,7 @@
                 qualified: true
                 config:
                     size-node-width-max: 440
+                    hub-node-count-max: 3
             props:
                 -   name: CATEGORY
                     desc: >
@@ -2615,8 +2697,18 @@
                 is a reference rendering of the final look of one screen (a low-fidelity sketch of
                 a screen within its flow is a Dialog Storyboard frame instead) and shows rules
                 applied rather than stating them (a rule is an `ELEMENT` instead).
+            optional: true
             format:
                 type: complex
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[MOCKUP:*]], [[PERSONA:*]], [[STORYBOARD:*]], [[ELEMENT:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    hub-node-count-max: 3
             props:
                 -   name: ACTORS
                     desc: >
@@ -2690,7 +2782,9 @@
                 solution deploys and operates itself (e.g. a managed database of its own) is a
                 Deployment View node instead -- only a party or system the solution merely consumes
                 or serves belongs to the system context.
+            optional: true
             format:
+                type: compact
                 maxTableColumns: 5
             props:
                 -   name: KIND
@@ -2807,13 +2901,16 @@
                 otherwise) and which elaborates how the component fulfills it and collaborates
                 with the components it depends on, plus a 1-sentence rationale ("why") for the
                 component's existence and boundary.
+            optional: true
             format:
+                type: compact
                 maxTableColumns: 5
             diagram:
                 type: hub
                 center: self
                 nodes: "[[FV.COMPONENT:*]], [[FR.REQUIREMENT:*]], [[INTERFACE:*]], [[DM.ENTITY:*]],
-                    [[UNIT:*]], [[NODE:*]], [[CONCERN:*]], [[TACTIC:*]], [[DECISION:*]]"
+                    [[UNIT:*]], [[NODE:*]], [[CONCERN:*]], [[TACTIC:*]], [[DECISION:*]],
+                    [[CODE-PATTERN:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -2821,6 +2918,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: KIND
                     desc: |
@@ -2925,6 +3023,7 @@
                                   or a shared module used by client and server), so a product
                                   used on several tiers is a single component here instead of
                                   one per tier; referenced by no Deployment View tier.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -2950,11 +3049,13 @@
                         carrying trade-off behind the choice is a Design Decisions decision
                         referencing the component through `DECIDES`, and the functional components
                         depending on the product reference it through `USED-BY`.
+                    format:
+                        type: compact
                     diagram:
                         type: hub
                         center: self
                         nodes: "[[TS.TIER:*.COMPONENT:*]], [[FV.COMPONENT:*]], [[CONCERN:*]],
-                            [[TACTIC:*]], [[DECISION:*]]"
+                            [[TACTIC:*]], [[DECISION:*]], [[CODE-PATTERN:*]]"
                         labeled: true
                         qualified: true
                         properties:
@@ -2963,6 +3064,7 @@
                         config:
                             size-node-width-max:    440
                             size-node-height-scale: 1.75
+                            hub-node-count-max:     3
                     props:
                         -   name: PRODUCT
                             desc: >
@@ -3276,12 +3378,15 @@
                 process: it names no concrete products (a Technology Stack `Build-Time` component
                 states the product choice), does not restate the runtime structure (a Functionality
                 View `Module` or `Subsystem` groups the logic), does not cover production
-                procedures (an Operations View concern does), and the trade-off that produced a
-                rule is a Design Decisions decision referencing the aspect through `AFFECTS`,
-                while the quality the rule protects (usually a `Maintainability` requirement) is
+                procedures (an Operations View concern does), does not prescribe how a concern is
+                coded (a Code Patterns pattern shows that as a listing), and the trade-off that
+                produced a rule is a Design Decisions decision referencing the aspect through
+                `AFFECTS`, while the quality the rule protects (usually a `Maintainability`
+                requirement) is
                 addressed by a Quality Perspectives tactic referencing the aspect through
                 `AFFECTS`, too, so the hub diagram of an aspect shows the decision and the tactic
                 behind it.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3342,6 +3447,7 @@
                 Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element
                 hosting a managed broker a Deployment View `Managed` node -- only the executing
                 structure itself belongs to the Concurrency View.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3353,6 +3459,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: KIND
                     desc: |
@@ -3441,6 +3548,7 @@
                 `TIER`, a location-level tier (e.g. a data center) groups the tiers referencing it
                 via `PART-OF`, and a single deployment unit within a tier is a `NODE` -- only the
                 partition itself belongs here.
+            optional: true
             format:
                 type: concise
             diagram:
@@ -3455,6 +3563,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: PART-OF
                     desc: >
@@ -3519,6 +3628,7 @@
                 itself belongs to the Deployment View, with the tier and area the node belongs to
                 and the network segments it is attached to as its `TIER`, `AREA`, and `NETWORK`
                 siblings.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3534,6 +3644,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: KIND
                     desc: |
@@ -3629,6 +3740,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: SCOPE
                     desc: |
@@ -3687,6 +3799,7 @@
                 deployable artifact is a `Build` aspect of the Development Aspects, and the products
                 used are Technology Stack `Operate-Time` components referenced through `TOOLS` --
                 only the procedure itself, its trigger, and its responsible operator belong here.
+            optional: true
             diagram:
                 type: hub
                 center: self
@@ -3700,6 +3813,7 @@
                 config:
                     size-node-width-max:    440
                     size-node-height-scale: 1.75
+                    hub-node-count-max:     3
             props:
                 -   name: CATEGORY
                     desc: |
@@ -3801,16 +3915,21 @@
                 Design Decisions decision referencing the tactic through `DECIDES`, the product
                 realizing the mechanism is a Technology Stack component referenced through
                 `TOOLS`, the developer-facing rule about the source structure is an aspect of the
-                Development Aspects, and a mechanism driven solely by a `Constraint` requirement
+                Development Aspects, the coded form of the mechanism is a Code Patterns pattern
+                referencing the tactic through `REALIZES`, and a mechanism driven solely by a
+                `Constraint` requirement
                 (e.g. a hosting or budget mandate) protects no quality and is a Design Decisions
                 decision alone -- only the mechanism, the quality it achieves, and the elements it
                 shapes belong here.
+            optional: true
+            format:
+                type: compact
             diagram:
                 type: hub
                 center: self
                 nodes: "[[TACTIC:*]], [[NR.REQUIREMENT:*]], [[FV.COMPONENT:*]], [[UNIT:*]],
                     [[ASPECT:*]], [[NODE:*]], [[DM.ENTITY:*]], [[CONCERN:*]], [[DECISION:*]],
-                    [[TS.TIER:*.COMPONENT:*]], [[TEST-CASE:*]]"
+                    [[TS.TIER:*.COMPONENT:*]], [[CODE-PATTERN:*]], [[TEST-CASE:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3885,9 +4004,10 @@
     file: 30-ARCH-DD-Design-Decisions.md
     desc: >
         The major decisions related to the solution design, each recording the forces at play, the
-        chosen response, and the reasoning that justifies it. The artifact is the last one of the
-        architecture, as a decision references the requirements forcing it, the elements it
-        shapes, and the tactics and products it chose, all of which precede it.
+        chosen response, and the reasoning that justifies it. The artifact is the last
+        decision-level one of the architecture, as a decision references the requirements forcing
+        it, the elements it shapes, and the tactics and products it chose, all of which precede
+        it, while the Code Patterns following it reference the decisions they implement.
     optional: true
     refs: >
         -   Nygard: Documenting Architecture Decisions (2011),
@@ -3963,15 +4083,18 @@
                 decision is under-justified. The rationale should make the decision feel earned,
                 not asserted - if you delete the rationale and the decision suddenly looks
                 arbitrary, the rationale was doing its job.
+            optional: true
+            format:
+                type: complex
             diagram:
                 type: hub
                 center: self
                 nodes: "[[DECISION:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[DM.ENTITY:*]],
                     [[LIFECYCLE:*]], [[ROLE:*]], [[INTERFACE:*]], [[TYPE:*]], [[ENDPOINT:*]],
-                    [[PRINCIPLE:*]], [[CONVENTION:*]], [[PATTERN:*]], [[STORYBOARD:*]],
+                    [[PRINCIPLE:*]], [[CONVENTION:*]], [[DIALOG-PATTERN:*]], [[STORYBOARD:*]],
                     [[ELEMENT:*]], [[CV.ENTITY:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]],
                     [[DV.TIER:*]], [[AREA:*]], [[NODE:*]], [[NETWORK:*]], [[TACTIC:*]],
-                    [[TS.TIER:*.COMPONENT:*]]"
+                    [[TS.TIER:*.COMPONENT:*]], [[CODE-PATTERN:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -4019,7 +4142,7 @@
                         integrated); omitted for a decision shaping no modeled element.
                     value: list([[DM.ENTITY:*]], [[LIFECYCLE:*]], [[ROLE:*]], [[INTERFACE:*]],
                         [[TYPE:*]], [[ENDPOINT:*]], [[PRINCIPLE:*]], [[CONVENTION:*]],
-                        [[PATTERN:*]], [[STORYBOARD:*]], [[ELEMENT:*]], [[CV.ENTITY:*]],
+                        [[DIALOG-PATTERN:*]], [[STORYBOARD:*]], [[ELEMENT:*]], [[CV.ENTITY:*]],
                         [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]], [[DV.TIER:*]], [[AREA:*]],
                         [[NODE:*]], [[NETWORK:*]])
                     optional: true
@@ -4115,10 +4238,124 @@
                             matrix of considered alternatives); and
                         -   links to strongly related decisions.
                     optional: true
+
+-   kind: ARCH
+    name: Code Patterns
+    id: CP
+    file: 31-ARCH-CP-Code-Patterns.md
+    desc: >
+        The implementation patterns the source code of the solution follows, each prescribing how
+        one recurring concern (e.g. authorization enforcement, entity persistence, error
+        propagation) is coded and showing it as a code listing. The artifact follows the Design
+        Decisions, as a pattern is the coded form of the tactics and decisions preceding it, and
+        is absent when the coding conventions are governed outside the specification (e.g. by
+        repository-level contributor instructions).
+    optional: true
+    refs: >
+        -   Starke/Hruschka: arc42 Template: Crosscutting Concepts (2005),
+            https://arc42.org/overview
+        -   Fowler: Patterns of Enterprise Application Architecture (2002),
+            https://martinfowler.com/books/eaa.html
+        -   Beck: Implementation Patterns (2007),
+            https://www.informit.com/store/implementation-patterns-9780321413093
+    diagram:
+        type: grid
+        nodes: "[[CODE-PATTERN:*]]"
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 4
+    children:
+        -   kind: CODE-PATTERN
+            desc: >
+                A single code pattern, named with a short (2-5 word) summary of the concern it
+                codes (e.g. `Endpoint Authorization`, `Entity Persistence`, `Error Propagation`)
+                and described in a concise (1-3 sentence) paragraph by the rule the code follows
+                whenever the concern arises, plus a 1-sentence rationale ("why") for the rule.
+
+                The listing showing the pattern follows the description and its rationale as the
+                elaboration of the pattern: either a fenced code block in the language of the
+                pattern (e.g. ` ```ts start=10 mark=3-5 `, the parameters numbering the lines
+                from `start` and marking the essential ones) or an embedded excerpt of an existing
+                source file (e.g. `![Entity Persistence](src/persistence.ts#lines=10-30&mark=3-5)`,
+                the fragment selecting and marking the lines), the latter preferred once the code
+                exists, as the specification then never drifts from it. The listing is the
+                canonical, idealized form of the pattern, not an exhaustive example, so it is kept
+                short (typically 10-30 lines) and the prose names what the listing cannot: the
+                places the pattern applies and the deviation it rules out (`AVOID`).
+
+                A pattern states how a concern is coded, and nothing else: the quality mechanism
+                it implements is a Quality Perspectives tactic referenced through `REALIZES`, the
+                trade-off that chose its approach over alternatives is a Design Decisions decision
+                referenced through `DECIDED-BY` (a pattern weighs no alternatives itself), the
+                product it codes against is a Technology Stack component referenced through
+                `TOOLS`, and the rule about the source layout, build, or process it lives in is a
+                Development Aspects aspect -- only the recurring code shape, the elements written
+                that way, and the deviation ruled out belong here.
+            optional: true
+            format:
+                type: complex
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[CODE-PATTERN:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[DM.ENTITY:*]],
+                    [[ROLE:*]], [[INTERFACE:*]], [[ENDPOINT:*]], [[TS.TIER:*.COMPONENT:*]],
+                    [[TACTIC:*]], [[DECISION:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: APPLIES-TO
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW, CONCURRENCY-VIEW,
+                        DATA-MODEL, AUTHORIZATION-MODEL, INTERFACE-MODEL, or INTERFACE-ENDPOINTS
+                        objects whose code follows the pattern (e.g. the components persisting
+                        their entities this way, the roles and endpoints guarded by the check);
+                        omitted for a pattern applied throughout the code base.
+                    value: list([[FV.COMPONENT:*]], [[UNIT:*]], [[DM.ENTITY:*]], [[ROLE:*]],
+                        [[INTERFACE:*]], [[ENDPOINT:*]])
+                    optional: true
+                -   name: REALIZES
+                    desc: >
+                        Comma-separated references to the QUALITY-PERSPECTIVES tactics the pattern
+                        is the coded form of (e.g. the token check implementing the access
+                        security tactic); omitted for a pattern serving no modeled tactic.
+                    value: list([[TACTIC:*]])
+                    optional: true
+                -   name: DECIDED-BY
+                    desc: >
+                        Comma-separated references to the DESIGN-DECISIONS objects the pattern
+                        implements (e.g. the query builder usage following the decision against an
+                        ORM); omitted for a pattern behind which no recorded decision stands.
+                    value: list([[DECISION:*]])
+                    optional: true
+                -   name: TOOLS
+                    desc: >
+                        Comma-separated references to the TECHNOLOGY-STACK components the pattern
+                        codes against (e.g. the query builder, the logging library); omitted for a
+                        pattern using the language alone.
+                    value: list([[TS.TIER:*.COMPONENT:*]])
+                    optional: true
+                -   name: USES
+                    desc: >
+                        Comma-separated references to the smaller CODE-PATTERNS objects the pattern
+                        is composed of (e.g. an `Endpoint Authorization` using the `Error
+                        Propagation` for its rejections), so that the patterns form a language of
+                        related shapes rather than a flat catalogue.
+                    value: list([[CODE-PATTERN:*]])
+                    optional: true
+                    acyclic: true
+                -   name: AVOID
+                    desc: >
+                        The deviation the pattern rules out, stated as the concrete shape a
+                        developer would otherwise reach for (e.g. `SQL strings assembled in the
+                        request handlers`, `role checks in the client alone`); omitted when the
+                        rule has no tempting alternative.
+                    optional: true
 -   kind: TEST
     name: Test Cases
     id: TC
-    file: 31-TEST-TC-Test-Cases.md
+    file: 32-TEST-TC-Test-Cases.md
     desc: >
         The verifiable conditions and steps used to confirm that requirements, domain rules, use
         case scenarios, state transitions, and the mechanisms, procedures, and decisions of the
@@ -4182,6 +4419,9 @@
                 concurrency unit when its collaboration or contention is exercised, an aspect of
                 the Development Aspects or a Design Decisions decision when its rule is checked by
                 an architectural fitness function (e.g. no dependency edge against the layering).
+            optional: true
+            format:
+                type: compact
             diagram:
                 type: hub
                 center: self
@@ -4195,6 +4435,7 @@
                 config:
                     size-node-width-max: 440
                     size-node-height-scale: 1.75
+                    hub-node-count-max: 3
             props:
                 -   name: VERIFIES
                     desc: >