@rse/specbook 1.4.2 → 1.5.1

package/dst/specbook-export-diagram.js

@@ -124,9 +124,9 @@ const d2Error = (err) => {
         return message;
     }
 };
-/*  render a D2 diagram, with the theme colors prepended as one line of
-    theme overrides (on the theme of the style), so the overrides of the
-    diagram itself still win  */
+/*  render a D2 diagram, with the TALA layout engine and the theme colors
+    prepended as one line of configuration (on the theme of the style),
+    so the configuration of the diagram itself still wins  */
 const renderD2 = (source, colors, style) => {
     const overrides = Object.entries(colors).map(([key, color]) => `${key}: "${color}"`).join("; ");
     const request = d2Chain.then(async () => {
@@ -140,7 +140,7 @@ const renderD2 = (source, colors, style) => {
         worker()?.ref();
         try {
             const result = await compiler.compile({
-                fs: { index: `vars: { d2-config: { theme-overrides: { ${overrides} } } }\n${source}` },
+                fs: { index: `vars: { d2-config: { layout-engine: tala; theme-overrides: { ${overrides} } } }\n${source}` },
                 options: { themeID: style === "dark" ? 200 : 0, scale: 1, pad: 0, noXMLTag: true }
             });
             return await compiler.render(result.diagram, result.renderOptions);

package/dst/specbook-format.md

@@ -1148,8 +1148,10 @@ its own and embedded like an image -- `![<alt/>](<file/>.mmd)`,
 `![<alt/>](<file/>.mermaid)`, or `![<alt/>](<file/>.d2)` -- inside a
 description or property value, where its source is inlined at parse time.
 The HTML/PDF export renders every such diagram (Mermaid through
-`beautiful-mermaid`, D2 through `@d2lang/d2`) in the theme colors of
-the document, once per color theme, like a theme-aware image. It folds,
+`beautiful-mermaid`, D2 through `@d2lang/d2`, laid out by its TALA
+engine unless the diagram configures another `layout-engine`) in the
+theme colors of the document, once per color theme, like a theme-aware
+image. It folds,
 maximizes, and is omitted (`-O diagram:code`, for diagrams as code, or
 by nesting level) like a derived Gradia diagram. A diagram failing to render
 is omitted with a notice. The normalized Markdown and the AST exports

package/dst/specbook-format.yaml

@@ -642,7 +642,10 @@
     desc: >
         The concrete behaviors and capabilities the solution must provide, describing *what* the
         system does in terms of functions, features, and operations, while the quality bounds and
-        constraints on them belong to the Non-Functional Requirements.
+        constraints on them belong to the Non-Functional Requirements. The requirements are
+        optionally grouped into the coherent capabilities they add up to (the epics of agile
+        planning, the features of product management), which the overview diagram draws as boxes
+        around their requirements.
     optional: true
     refs: >
         -   Mavin et al.: Easy Approach to Requirements Syntax (EARS) (2009),
@@ -654,12 +657,31 @@
     diagram:
         type: grid
         nodes: "[[FR.REQUIREMENT:*]]"
+        nest:
+            properties:
+                -   GROUP
         properties:
             -   PRIORITY
         config:
             size-node-width-max: 440
-            grid-columns-max: 4
+            grid-columns-max: 2
     children:
+        -   kind: GROUP
+            desc: >
+                A named group of strongly related requirements, carrying a short (1-3 word),
+                per-artifact unique name distinct from the names of its requirements (e.g.
+                `Moderation` for the moderating, forwarding, and answering of attendee inputs,
+                `Event Access` for the access URLs), and described by a 1-sentence description
+                ("what") of the capability the requirements add up to plus a 1-sentence rationale
+                ("why") of the cohesion. A group is an epic in the agile sense and a feature in the
+                product sense, but carries no obligation of its own: it has no priority, states no
+                behavior, and is verified through its requirements alone, so it affects the
+                overview diagram only, where its requirements are drawn next to each other inside
+                a box. The groups are listed before the requirements, and every requirement
+                belongs to at most one group.
+            optional: true
+            referenced:
+                -   "[[FR.REQUIREMENT:*]]"
         -   kind: REQUIREMENT
             desc: >
                 A single functional requirement, named with a short (3-8 word) summary and described
@@ -674,14 +696,15 @@
                 unwanted-behavior (`If <condition>, then the system MUST ...`).
             optional: true
             format:
-                maxTableColumns: 6
+                type: compact
             referenced:
                 -   "[[USE-CASE:*]]"
             diagram:
                 type: hub
                 center: self
-                nodes: "[[FR.REQUIREMENT:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[RULE:*]],
-                    [[USE-CASE:*]], [[DM.ENTITY:*]], [[FV.COMPONENT:*]], [[TEST-CASE:*]]"
+                nodes: "[[FR.GROUP:*]], [[FR.REQUIREMENT:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]],
+                    [[RULE:*]], [[USE-CASE:*]], [[DM.ENTITY:*]], [[FV.COMPONENT:*]],
+                    [[TEST-CASE:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -697,6 +720,23 @@
                         time"), preserving the conscious decision rather than silently dropping it,
                         with the statement still phrased as it would be if in scope.
                     value: enum(MUST,SHOULD,COULD,WONT)
+                -   name: GROUP
+                    desc: >
+                        Reference to the FUNCTIONAL-REQUIREMENTS group the requirement belongs to,
+                        placing it next to the other requirements of the group in the overview
+                        diagram; omitted for a requirement standing on its own.
+                    value: "[[FR.GROUP:*]]"
+                    optional: true
+                -   name: DEPENDS-ON
+                    desc: >
+                        Comma-separated references to the FUNCTIONAL-REQUIREMENTS objects the
+                        requirement presupposes, i.e. whose behavior has to exist before its own
+                        makes sense (e.g. replying to chat messages presupposes chat messages),
+                        so that dropping or deferring a requirement reveals what falls with it;
+                        omitted for a requirement presupposing no other one.
+                    value: list([[FR.REQUIREMENT:*]])
+                    optional: true
+                    acyclic: true
                 -   name: PREMISES
                     desc: >
                         Comma-separated references to the SOLUTION-PREMISES objects the
@@ -748,6 +788,8 @@
                 exception the lint warning cannot tell apart) and its hub diagram shows what
                 answers it.
             optional: true
+            format:
+                type: compact
             referenced:
                 -   "[[TACTIC:*]]"
                 -   "[[DECISION:*]]"
@@ -1145,7 +1187,7 @@
                 center: self
                 nodes: "[[USE-CASE:*]], [[ROLE:*]], [[PERSONA:*]], [[STEP:*]], [[ACTIVITY:*]],
                     [[FR.REQUIREMENT:*]], [[RULE:*]], [[DM.ENTITY:*]], [[TRANSITION:*]],
-                    [[PERMISSION:*]], [[PRINCIPLE:*]], [[STORYBOARD:*]], [[CV.ENTITY:*]],
+                    [[PERMISSION:*]], [[IC.PRINCIPLE:*]], [[STORYBOARD:*]], [[CV.ENTITY:*]],
                     [[TEST-CASE:*]]"
                 labeled: true
                 qualified: true
@@ -2230,7 +2272,7 @@
     optional: true
     diagram:
         type: grid
-        nodes: "[[PRINCIPLE:*]]"
+        nodes: "[[IC.PRINCIPLE:*]]"
         properties:
             -   CATEGORY
         config:
@@ -2246,8 +2288,10 @@
                 solution, plus a 1-sentence rationale ("why"). A principle is solution-wide and
                 independent of any particular screen or flow (a structure recurring within one flow
                 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).
+                it rejects is its `TRADE-OFF`), is not verifiable by a metric (a measurable
+                quality bound is a Non-Functional Requirement instead), and governs the user's
+                experience (a principle governing the architecture is an Architecture Tenets
+                principle instead).
             optional: true
             referenced:
                 -   "[[DIALOG-PATTERN:*]]"
@@ -2256,7 +2300,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[PRINCIPLE:*]], [[PERSONA:*]], [[STEP:*]], [[USE-CASE:*]], [[CONVENTION:*]],
+                nodes: "[[IC.PRINCIPLE:*]], [[PERSONA:*]], [[STEP:*]], [[USE-CASE:*]], [[CONVENTION:*]],
                     [[DIALOG-PATTERN:*]], [[ELEMENT:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
@@ -2354,7 +2398,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[CONVENTION:*]], [[PERSONA:*]], [[PRINCIPLE:*]], [[TERM:*]], [[DECISION:*]]"
+                nodes: "[[CONVENTION:*]], [[PERSONA:*]], [[IC.PRINCIPLE:*]], [[TERM:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -2383,7 +2427,7 @@
                         Comma-separated references to the INTERACTION-CONCEPT objects the convention
                         supports in wording, so that a convention is grounded in the interaction
                         philosophy rather than in taste alone.
-                    value: list([[PRINCIPLE:*]])
+                    value: list([[IC.PRINCIPLE:*]])
                     optional: true
                 -   name: TERMS
                     desc: >
@@ -2438,7 +2482,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[DIALOG-PATTERN:*]], [[PRINCIPLE:*]], [[STORYBOARD:*]], [[DECISION:*]]"
+                nodes: "[[DIALOG-PATTERN:*]], [[IC.PRINCIPLE:*]], [[STORYBOARD:*]], [[DECISION:*]]"
                 deep: true
                 labeled: true
                 qualified: true
@@ -2475,7 +2519,7 @@
                         Comma-separated references to the INTERACTION-CONCEPT objects the pattern
                         embodies, so that every principle is shown to be honored by at least one
                         pattern rather than merely declared.
-                    value: list([[PRINCIPLE:*]])
+                    value: list([[IC.PRINCIPLE:*]])
                     optional: true
                 -   name: USES
                     desc: >
@@ -2644,7 +2688,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[ELEMENT:*]], [[PERSONA:*]], [[PRINCIPLE:*]], [[MOCKUP:*]]"
+                nodes: "[[ELEMENT:*]], [[PERSONA:*]], [[IC.PRINCIPLE:*]], [[MOCKUP:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -2674,7 +2718,7 @@
                         Comma-separated references to the INTERACTION-CONCEPT objects the element
                         supports in appearance, so that an element is grounded in the interaction
                         philosophy rather than in taste alone.
-                    value: list([[PRINCIPLE:*]])
+                    value: list([[IC.PRINCIPLE:*]])
                     optional: true
                 -   name: SOURCE
                     desc: >
@@ -2734,10 +2778,218 @@
                         the design tool or a screenshot of an already existing user interface, so
                         that the look is seen rather than only read.
 
+-   kind: ARCH
+    name: Architecture Tenets
+    id: AT
+    file: 22-ARCH-AT-Architecture-Tenets.md
+    desc: >
+        The architecture philosophy of the solution, stated as the few overarching maxims and the
+        standing principles derived from them, which every pattern, view, tactic, decision, and
+        aspect of the architecture has to obey, while the reusable structures belong to the
+        Architecture Patterns and the concrete ones to the views following them. The maxims are listed in decreasing precedence, so that whenever two maxims conflict
+        in a particular design decision, the earlier one wins, and a principle conflict is settled
+        by the precedence of the maxims the principles derive from.
+
+        The tenets are prescriptive and reusable, not verifiable and not decided once: a quality
+        bound verifiable by a metric is a Non-Functional Requirement, the mechanism achieving a
+        quality is a Quality Perspectives tactic, the rule about the source structure and process
+        is a Development Aspects aspect, the one-off trade-off between genuine alternatives is a
+        Design Decisions decision (which applies the tenets through `GUIDED-BY`), and the
+        principle governing the user's experience is an Interaction Concept principle.
+    optional: true
+    refs: >
+        -   The Open Group: TOGAF Standard, 10th ed.: Architecture Principles (2022),
+            https://pubs.opengroup.org/togaf-standard/adm-techniques/chap02.html
+        -   Greefhorst/Proper: Architecture Principles: The Cornerstones of Enterprise Architecture (2011),
+            https://link.springer.com/book/10.1007/978-3-642-20279-7
+        -   Starke/Hruschka: arc42 Template: Solution Strategy (2005),
+            https://arc42.org/overview
+    diagram:
+        type: grid
+        nodes: "[[MAXIM:*]], [[AT.PRINCIPLE:*]]"
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 4
+    children:
+        -   kind: MAXIM
+            desc: >
+                A single architecture maxim, named with a short (2-5 word) preference or imperative
+                (e.g. `Simplicity over Flexibility`, `Buy before Build`, `Own the Data`) and
+                described in a concise (1-3 sentence) paragraph by how it guides the architecture
+                of the solution as a whole, plus a 1-sentence rationale ("why"). A solution has only
+                a few (3-7) maxims: a maxim is solution-wide and independent of any particular view
+                or element (a rule bound to a structure is a principle instead), decides between
+                design alternatives (the subordinated side usually named by its `X over Y` form),
+                and is not verifiable by a metric (a measurable quality bound is a Non-Functional
+                Requirement instead).
+            optional: true
+            format:
+                type: compact
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[MAXIM:*]], [[AT.PRINCIPLE:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]],
+                    [[TACTIC:*]], [[DECISION:*]], [[ASPECT:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: DRIVEN-BY
+                    desc: >
+                        Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS or
+                        SOLUTION-PREMISES objects the maxim answers (e.g. the maintainability
+                        requirement, the small-team premise), so that a maxim is grounded in the
+                        forces on the solution rather than in taste alone; omitted for a maxim
+                        rooted in the Solution Vision alone.
+                    value: list([[NR.*]], [[PREMISE:*]])
+                    optional: true
+        -   kind: PRINCIPLE
+            desc: >
+                A single architecture principle, named with a short (2-5 word) summary (e.g.
+                `Stateless Services`, `One Owner per Entity`, `Async between Contexts`) and
+                described in a concise (1-3 sentence) paragraph as the standing rule the
+                architecture follows whenever its concern arises, stated with `MUST`/`MUST NOT`
+                or `SHOULD`/`SHOULD NOT`, plus a 1-sentence rationale ("why"). A principle is
+                bound to a particular structure of the architecture (a rule independent of any
+                structure is a maxim instead), reusable across many decisions (a trade-off made
+                once between genuine alternatives is a Design Decisions decision instead), names
+                no mechanism and no product (the mechanism is a Quality
+                Perspectives tactic, the product a Technology Stack component), and governs the
+                architecture, not the source process (a Development Aspects aspect), the code (a
+                Code Patterns pattern), or the user's experience (an Interaction Concept
+                principle).
+            optional: true
+            format:
+                type: compact
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[MAXIM:*]], [[AT.PRINCIPLE:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]],
+                    [[TACTIC:*]], [[DECISION:*]], [[ASPECT:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: MAXIMS
+                    desc: >
+                        Comma-separated references to the MAXIM objects the principle
+                        concretizes (e.g. a `Stateless Services` principle concretizing a
+                        `Scale Out over Scale Up` maxim), so that the principles form a hierarchy
+                        below the maxims rather than a flat catalogue; omitted for a principle
+                        standing on its own forces alone.
+                    value: list([[MAXIM:*]])
+                    optional: true
+                -   name: DRIVEN-BY
+                    desc: >
+                        Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS or
+                        SOLUTION-PREMISES objects the principle answers beyond the maxims it
+                        concretizes (e.g. the availability requirement, the hosting constraint);
+                        omitted for a principle grounded in its maxims alone.
+                    value: list([[NR.*]], [[PREMISE:*]])
+                    optional: true
+                -   name: IMPLICATIONS
+                    desc: >
+                        What following the principle obliges the architecture to, stated as a 1-2
+                        sentence description of the consequences for the elements it governs
+                        (e.g. `session state lives in the shared store, so every component
+                        instance is replaceable at any time`), as opposed to the rationale which
+                        states why the principle is worth these consequences; omitted when nothing
+                        non-obvious follows from the principle.
+                    optional: true
+
+-   kind: ARCH
+    name: Architecture Patterns
+    id: AP
+    file: 23-ARCH-AP-Architecture-Patterns.md
+    desc: >
+        The reusable structural solutions the architecture of the solution follows, each a named
+        pattern of the literature or of the organization (e.g. hexagonal architecture,
+        transactional outbox, backend for frontend) applied to the solution as a whole, which the
+        views following them realize, the tactics build upon, the decisions choose, and the code
+        patterns code. The artifact completes the guidance of the architecture: the Architecture
+        Tenets state what the architecture values and obeys, the patterns state the structures it
+        takes to do so.
+
+        A pattern names a structure, nothing else: the mechanism achieving one quality attribute
+        is a Quality Perspectives tactic (which may be built from patterns), the one-off trade-off
+        choosing a pattern over its alternatives is a Design Decisions decision, the coded form of
+        a pattern is a Code Patterns pattern shown as a listing, and a structure of the user
+        interface is a Dialog Patterns pattern.
+    optional: true
+    refs: >
+        -   Buschmann et al.: Pattern-Oriented Software Architecture, Vol. 1: A System of Patterns (1996),
+            https://www.wiley.com/en-us/Pattern+Oriented+Software+Architecture%2C+Volume+1%2C+A+System+of+Patterns-p-9780471958697
+        -   Fowler: Patterns of Enterprise Application Architecture (2002),
+            https://martinfowler.com/books/eaa.html
+        -   Hohpe/Woolf: Enterprise Integration Patterns (2003),
+            https://www.enterpriseintegrationpatterns.com/
+        -   Richardson: Microservices Patterns (2018),
+            https://microservices.io/patterns/
+    diagram:
+        type: grid
+        nodes: "[[PATTERN:*]]"
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 4
+    children:
+        -   kind: PATTERN
+            desc: >
+                A single architecture pattern, named with its established short (2-5 word) name
+                (e.g. `Hexagonal Architecture`, `Transactional Outbox`, `Backend for Frontend`)
+                and described in a concise (1-3 sentence) paragraph by the structure the pattern
+                prescribes and the problem it solves in the solution, plus a 1-sentence rationale
+                ("why") for adopting it. A pattern is a structure reusable beyond one quality
+                attribute (a mechanism for one quality is a Quality Perspectives tactic instead)
+                and beyond one decision (a trade-off made once is a Design Decisions decision
+                instead), applies the Architecture Tenets rather than restating them, and is
+                realized by the elements of the views following it, which reference it, so its
+                hub diagram shows where it took effect.
+            optional: true
+            format:
+                type: compact
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[PATTERN:*]], [[AT.PRINCIPLE:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]],
+                    [[FV.COMPONENT:*]], [[TACTIC:*]], [[DECISION:*]], [[CODE-PATTERN:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: PRINCIPLES
+                    desc: >
+                        Comma-separated references to the ARCHITECTURE-TENETS principles the
+                        pattern applies (e.g. a `Transactional Outbox` applying an `Async between
+                        Contexts` principle), so that a pattern is adopted for a stated stance of
+                        the architecture rather than for its popularity; omitted for a pattern
+                        applying no modeled principle.
+                    value: list([[AT.PRINCIPLE:*]])
+                    optional: true
+                -   name: DRIVEN-BY
+                    desc: >
+                        Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS or
+                        SOLUTION-PREMISES objects the pattern answers beyond the principles it
+                        applies (e.g. the scalability requirement, the hosting constraint); omitted
+                        for a pattern grounded in its principles alone.
+                    value: list([[NR.*]], [[PREMISE:*]])
+                    optional: true
+                -   name: USES
+                    desc: >
+                        Comma-separated references to the smaller ARCHITECTURE-PATTERNS objects
+                        the pattern is composed of (e.g. a `Saga` using a `Transactional Outbox`
+                        for its steps), so that the patterns form a language of related structures
+                        rather than a flat catalogue.
+                    value: list([[PATTERN:*]])
+                    optional: true
+                    acyclic: true
+
 -   kind: ARCH
     name: Context View
     id: CV
-    file: 22-ARCH-CV-Context-View.md
+    file: 24-ARCH-CV-Context-View.md
     desc: >
         The relationships, dependencies, and interactions between the solution and its environment,
         defining the system's boundary by enumerating the external entities sitting at it. The
@@ -2869,7 +3121,7 @@
 -   kind: ARCH
     name: Functionality View
     id: FV
-    file: 23-ARCH-FV-Functionality-View.md
+    file: 25-ARCH-FV-Functionality-View.md
     desc: >
         The functional components of the solution, their responsibilities, interfaces, and primary
         interactions, describing *how* the solution's runtime elements are structured and which
@@ -2908,9 +3160,9 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[FV.COMPONENT:*]], [[FR.REQUIREMENT:*]], [[INTERFACE:*]], [[DM.ENTITY:*]],
-                    [[UNIT:*]], [[NODE:*]], [[CONCERN:*]], [[TACTIC:*]], [[DECISION:*]],
-                    [[CODE-PATTERN:*]]"
+                nodes: "[[FV.COMPONENT:*]], [[FR.REQUIREMENT:*]], [[PATTERN:*]], [[INTERFACE:*]],
+                    [[DM.ENTITY:*]], [[UNIT:*]], [[NODE:*]], [[CONCERN:*]], [[TACTIC:*]],
+                    [[DECISION:*]], [[CODE-PATTERN:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -2948,6 +3200,14 @@
                         that every Functional Requirement is owned by at least one component.
                     value: list([[FR.*]])
                     optional: true
+                -   name: PATTERNS
+                    desc: >
+                        Comma-separated references to the ARCHITECTURE-PATTERNS objects the
+                        structure of the component follows (e.g. the service shaped by a
+                        `Hexagonal Architecture`, the publisher keeping a `Transactional Outbox`);
+                        omitted for a component following no modeled pattern.
+                    value: list([[PATTERN:*]])
+                    optional: true
                 -   name: OWNS
                     desc: >
                         Comma-separated references to the DATA-MODEL entities the component owns,
@@ -2986,7 +3246,7 @@
 -   kind: ARCH
     name: Technology Stack
     id: TS
-    file: 24-ARCH-TS-Technology-Stack.md
+    file: 26-ARCH-TS-Technology-Stack.md
     desc: >
         The concrete technology products the solution is built upon, organized by tier and lifecycle
         phase, recording for each component its chosen product, its purpose, and the alternatives
@@ -3347,7 +3607,7 @@
 -   kind: ARCH
     name: Development Aspects
     id: DA
-    file: 25-ARCH-DA-Development-Aspects.md
+    file: 27-ARCH-DA-Development-Aspects.md
     desc: >
         The architecture supporting the software development process, defining the module
         organization, build approach, and codeline conventions. The artifact is absent when the
@@ -3379,18 +3639,20 @@
                 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), does not prescribe how a concern is
-                coded (a Code Patterns pattern shows that as a listing), and the trade-off that
+                coded (a Code Patterns pattern shows that as a listing), the tenet the rule
+                concretizes is an Architecture Tenets maxim or principle referenced through
+                `GUIDED-BY`, 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.
+                `AFFECTS`, too, so the hub diagram of an aspect shows the tenet, the decision, and
+                the tactic behind it.
             optional: true
             diagram:
                 type: hub
                 center: self
-                nodes: "[[ASPECT:*]], [[TACTIC:*]], [[DECISION:*]]"
+                nodes: "[[ASPECT:*]], [[MAXIM:*]], [[AT.PRINCIPLE:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3408,11 +3670,19 @@
                         standards and conventions), `Testing` (test conventions, layout, and
                         coverage rules), or `Tooling` (development tools and automation).
                     value: enum(Structure,Build,Dependency,Codeline,Standardization,Testing,Tooling)
+                -   name: GUIDED-BY
+                    desc: >
+                        Comma-separated references to the ARCHITECTURE-TENETS objects the aspect
+                        concretizes for the source structure and process (e.g. the module
+                        layering following a `Dependencies Point Inward` principle); omitted for
+                        an aspect concretizing no modeled tenet.
+                    value: list([[MAXIM:*]], [[AT.PRINCIPLE:*]])
+                    optional: true
 
 -   kind: ARCH
     name: Concurrency View
     id: CO
-    file: 26-ARCH-CO-Concurrency-View.md
+    file: 28-ARCH-CO-Concurrency-View.md
     desc: >
         The concurrency structure of the solution, mapping functional components to processes and
         threads, and defining how they coordinate and communicate. The artifact is absent when the
@@ -3507,7 +3777,7 @@
 -   kind: ARCH
     name: Deployment View
     id: DV
-    file: 27-ARCH-DV-Deployment-View.md
+    file: 29-ARCH-DV-Deployment-View.md
     desc: >
         The environment into which the solution is deployed, partitioning it into tiers and mapping
         software elements to the runtime platform, hardware, and network topology.
@@ -3762,7 +4032,7 @@
 -   kind: ARCH
     name: Operations View
     id: OV
-    file: 28-ARCH-OV-Operations-View.md
+    file: 30-ARCH-OV-Operations-View.md
     desc: >
         The way the solution is operated, administered, and supported in production, defining the
         standing procedures by which the operating organization installs, configures, migrates,
@@ -3877,7 +4147,7 @@
 -   kind: ARCH
     name: Quality Perspectives
     id: QP
-    file: 29-ARCH-QP-Quality-Perspectives.md
+    file: 31-ARCH-QP-Quality-Perspectives.md
     desc: >
         How the Non-Functional Requirements (NR) are addressed by the architecture, through the
         tactics built into the solution across the views.
@@ -3911,7 +4181,11 @@
                 mechanism has to meet is the `METRIC` of the addressed Non-Functional Requirement
                 and is not restated, the production procedure performed against the mechanism
                 (e.g. scaling out, restoring) is an Operations View concern referenced through
-                `OPERATED-BY`, the trade-off that chose the mechanism over alternatives is a
+                `OPERATED-BY`, the tenet the mechanism follows is an Architecture Tenets maxim or
+                principle referenced through `GUIDED-BY`, the structure it is built from is an
+                Architecture Patterns pattern referenced through `PATTERNS`, the trade-off that
+                chose the mechanism
+                over alternatives is a
                 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
@@ -3927,9 +4201,10 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[TACTIC:*]], [[NR.REQUIREMENT:*]], [[FV.COMPONENT:*]], [[UNIT:*]],
-                    [[ASPECT:*]], [[NODE:*]], [[DM.ENTITY:*]], [[CONCERN:*]], [[DECISION:*]],
-                    [[TS.TIER:*.COMPONENT:*]], [[CODE-PATTERN:*]], [[TEST-CASE:*]]"
+                nodes: "[[TACTIC:*]], [[NR.REQUIREMENT:*]], [[MAXIM:*]], [[AT.PRINCIPLE:*]],
+                    [[PATTERN:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]], [[NODE:*]],
+                    [[DM.ENTITY:*]], [[CONCERN:*]], [[DECISION:*]], [[TS.TIER:*.COMPONENT:*]],
+                    [[CODE-PATTERN:*]], [[TEST-CASE:*]]"
                 labeled: true
                 qualified: true
                 properties:
@@ -3959,6 +4234,22 @@
                         Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS objects the
                         tactic addresses.
                     value: list([[NR.*]])
+                -   name: GUIDED-BY
+                    desc: >
+                        Comma-separated references to the ARCHITECTURE-TENETS objects the
+                        mechanism of the tactic follows (e.g. the stateless replication following
+                        a `Stateless Services` principle); omitted for a tactic following no
+                        modeled tenet.
+                    value: list([[MAXIM:*]], [[AT.PRINCIPLE:*]])
+                    optional: true
+                -   name: PATTERNS
+                    desc: >
+                        Comma-separated references to the ARCHITECTURE-PATTERNS objects the
+                        mechanism of the tactic is built from (e.g. the failover built on a
+                        `Circuit Breaker`), while `MECHANISM` states the mechanism itself; omitted
+                        for a tactic built from no modeled pattern.
+                    value: list([[PATTERN:*]])
+                    optional: true
                 -   name: MECHANISM
                     desc: >
                         The design mechanism through which the tactic is applied to achieve the
@@ -4001,7 +4292,7 @@
 -   kind: ARCH
     name: Design Decisions
     id: DD
-    file: 30-ARCH-DD-Design-Decisions.md
+    file: 32-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
@@ -4068,7 +4359,10 @@
                 A constraint itself is not a decision: a compliance obligation, a hosting mandate,
                 or a partner-imposed threshold is a Non-Functional Requirement (of category
                 `Compliance`, `Constraint`, or the affected quality), and the decision is the
-                response to it, referencing it through `DRIVEN-BY`.
+                response to it, referencing it through `DRIVEN-BY`. A standing rule is not a
+                decision either: a maxim or principle reusable across many decisions is an
+                Architecture Tenets object, and the decision applies it, referencing it through
+                `GUIDED-BY`.
 
                 `WHEN`, `WHAT`, and `WHY` are each just a single paragraph of concise and brief
                 prose text, usually comprised of just 1 to 3 sentences. The value of a decision is
@@ -4089,11 +4383,12 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[DECISION:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[DM.ENTITY:*]],
-                    [[LIFECYCLE:*]], [[ROLE:*]], [[INTERFACE:*]], [[TYPE:*]], [[ENDPOINT:*]],
-                    [[PRINCIPLE:*]], [[CONVENTION:*]], [[DIALOG-PATTERN:*]], [[STORYBOARD:*]],
-                    [[ELEMENT:*]], [[CV.ENTITY:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]],
-                    [[DV.TIER:*]], [[AREA:*]], [[NODE:*]], [[NETWORK:*]], [[TACTIC:*]],
+                nodes: "[[DECISION:*]], [[NR.REQUIREMENT:*]], [[PREMISE:*]], [[MAXIM:*]],
+                    [[AT.PRINCIPLE:*]], [[PATTERN:*]], [[DM.ENTITY:*]], [[LIFECYCLE:*]], [[ROLE:*]],
+                    [[INTERFACE:*]], [[TYPE:*]], [[ENDPOINT:*]], [[IC.PRINCIPLE:*]],
+                    [[CONVENTION:*]], [[DIALOG-PATTERN:*]], [[STORYBOARD:*]], [[ELEMENT:*]],
+                    [[CV.ENTITY:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]], [[DV.TIER:*]],
+                    [[AREA:*]], [[NODE:*]], [[NETWORK:*]], [[TACTIC:*]],
                     [[TS.TIER:*.COMPONENT:*]], [[CODE-PATTERN:*]]"
                 labeled: true
                 qualified: true
@@ -4130,6 +4425,15 @@
                         and only exceptionally a premise alone, and a decision finding no
                         requirement to name reveals a missing one rather than a needless reference.
                     value: list([[NR.*]], [[PREMISE:*]])
+                -   name: GUIDED-BY
+                    desc: >
+                        Comma-separated references to the ARCHITECTURE-TENETS objects the decision
+                        applies (e.g. the `Buy before Build` maxim settling the choice of a managed
+                        service, the `Async between Contexts` principle settling the integration
+                        style), anchoring the principles the rationale `WHY` rests on; omitted for
+                        a decision applying no modeled tenet.
+                    value: list([[MAXIM:*]], [[AT.PRINCIPLE:*]])
+                    optional: true
                 -   name: AFFECTS
                     desc: >
                         Comma-separated references to the objects of the DATA, APIS, UXUI, or ARCH
@@ -4141,18 +4445,19 @@
                         chosen over a native one, the components split, the external system
                         integrated); omitted for a decision shaping no modeled element.
                     value: list([[DM.ENTITY:*]], [[LIFECYCLE:*]], [[ROLE:*]], [[INTERFACE:*]],
-                        [[TYPE:*]], [[ENDPOINT:*]], [[PRINCIPLE:*]], [[CONVENTION:*]],
+                        [[TYPE:*]], [[ENDPOINT:*]], [[IC.PRINCIPLE:*]], [[CONVENTION:*]],
                         [[DIALOG-PATTERN:*]], [[STORYBOARD:*]], [[ELEMENT:*]], [[CV.ENTITY:*]],
                         [[FV.COMPONENT:*]], [[UNIT:*]], [[ASPECT:*]], [[DV.TIER:*]], [[AREA:*]],
                         [[NODE:*]], [[NETWORK:*]])
                     optional: true
                 -   name: DECIDES
                     desc: >
-                        Comma-separated references to the QUALITY-PERSPECTIVES tactics or
-                        TECHNOLOGY-STACK components the decision chose over their alternatives,
-                        i.e. the mechanism or product which exists because of this decision; omitted
-                        when the decision chose no modeled tactic or product.
-                    value: list([[TACTIC:*]], [[TS.TIER:*.COMPONENT:*]])
+                        Comma-separated references to the ARCHITECTURE-PATTERNS objects,
+                        QUALITY-PERSPECTIVES tactics, or TECHNOLOGY-STACK components the decision
+                        chose over their alternatives, i.e. the pattern, mechanism, or product
+                        which exists because of this decision; omitted when the decision chose no
+                        modeled pattern, tactic, or product.
+                    value: list([[PATTERN:*]], [[TACTIC:*]], [[TS.TIER:*.COMPONENT:*]])
                     optional: true
                 -   name: ALTERNATIVES
                     desc: >
@@ -4242,7 +4547,7 @@
 -   kind: ARCH
     name: Code Patterns
     id: CP
-    file: 31-ARCH-CP-Code-Patterns.md
+    file: 33-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
@@ -4283,8 +4588,9 @@
                 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
+                A pattern states how a concern is coded, and nothing else: the structure or the
+                quality mechanism it implements is an Architecture Patterns pattern or 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
@@ -4299,7 +4605,7 @@
                 center: self
                 nodes: "[[CODE-PATTERN:*]], [[FV.COMPONENT:*]], [[UNIT:*]], [[DM.ENTITY:*]],
                     [[ROLE:*]], [[INTERFACE:*]], [[ENDPOINT:*]], [[TS.TIER:*.COMPONENT:*]],
-                    [[TACTIC:*]], [[DECISION:*]]"
+                    [[PATTERN:*]], [[TACTIC:*]], [[DECISION:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -4317,10 +4623,12 @@
                     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:*]])
+                        Comma-separated references to the ARCHITECTURE-PATTERNS objects or
+                        QUALITY-PERSPECTIVES tactics the pattern is the coded form of (e.g. the
+                        port interface coding the hexagonal architecture, the token check
+                        implementing the access security tactic); omitted for a pattern serving
+                        no modeled architecture pattern or tactic.
+                    value: list([[PATTERN:*]], [[TACTIC:*]])
                     optional: true
                 -   name: DECIDED-BY
                     desc: >
@@ -4355,7 +4663,7 @@
 -   kind: TEST
     name: Test Cases
     id: TC
-    file: 32-TEST-TC-Test-Cases.md
+    file: 34-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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.4.2",
+    "version":                             "1.5.1",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",
@@ -26,7 +26,7 @@
         "sharp":                           "0.35.5",
         "svgo":                            "4.1.0",
         "@rse/mrcs":                       "0.9.2",
-        "@rse/gradia":                     "1.4.2",
+        "@rse/gradia":                     "1.4.3",
         "beautiful-mermaid":               "1.1.3",
         "@d2lang/d2":                      "0.1.34",
         "shiki":                           "4.5.0",
@@ -48,7 +48,7 @@
         "picomatch":                       "4.0.7",
         "es-toolkit":                      "1.52.0",
         "fastify":                         "5.12.5",
-        "@fastify/websocket":              "11.3.3",
+        "@fastify/websocket":              "11.3.4",
         "@modelcontextprotocol/sdk":       "1.32.1",
         "zod":                             "4.6.5"
     },
@@ -58,12 +58,12 @@
         "@eslint/js":                      "10.0.1",
         "typescript-eslint":               "8.71.1",
         "eslint-plugin-promise":           "7.3.0",
-        "neostandard":                     "0.14.0-next.1",
+        "neostandard":                     "0.14.0",
         "globals":                         "17.13.0",
-        "eslint-plugin-yml":               "3.8.1",
+        "eslint-plugin-yml":               "3.9.0",
         "markdownlint":                    "0.41.1",
         "markdownlint-cli2":               "0.23.3",
-        "@types/node":                     "26.6.4",
+        "@types/node":                     "26.6.5",
         "@types/picomatch":                "4.0.3",
         "@types/subset-font":              "2.3.0",
         "@types/nunjucks":                 "3.2.6",