@rse/ase 0.9.1 → 0.9.3

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

@@ -7,11 +7,20 @@ Architecture (ARCH)
 The **Artifact Set** **Architecture (ARCH)** specifies the "input"
 and the "how" of the Software Engineering project.
 
-Each **Artifact** of the **Artifact Set** **Architecture (ARCH)**
-is stored under `docs/arch/ARCH-<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**
+**Architecture (ARCH)** is stored under
+`docs/arch/ARCH-<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. `Context-View`).
+
+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,41 +35,62 @@ The **Artifact Set** **Architecture (ARCH)** consists of the following
 distinct **Artifact**s (listed under their <artifact-name/> and their
 <artifact-id/>):
 
--   **Context View (CV)**:
+01. **Context View (CV)**:
     The relationships, dependencies, and interactions between the solution
     and its environment, defining the system's scope, external entities,
     and boundaries.
 
--   **Functionality View (FV)**:
-    The functional elements of the solution, their responsibilities,
+02. **Functionality View (FV)**:
+    The functional components of the solution, their responsibilities,
     interfaces, and primary interactions, describing *what* the system does
     at runtime.
 
--   **Information View (IV)**:
+03. **Information View (IV)**:
     The way the solution stores, manages, manipulates, and distributes
     information, defining the static data structure and dynamic information
     flow.
 
--   **Concurrency View (CO)**:
-    The concurrency structure of the solution, mapping functional elements
+04. **Concurrency View (CO)**:
+    The concurrency structure of the solution, mapping functional components
     to processes and threads, and defining how they coordinate and
     communicate.
 
--   **Development View (DV)**:
+05. **Development View (DV)**:
     The architecture supporting the software development process, defining
     the module organization, build approach, and codeline conventions.
 
--   **Deployment View (DP)**:
+06. **Deployment View (DP)**:
     The environment into which the solution is deployed, mapping software
     elements to the runtime platform, hardware, and network topology.
 
--   **Operations View (OV)**:
+07. **Operations View (OV)**:
     The way the solution is operated, administered, and supported in
     production, defining installation, monitoring, and management concerns.
 
--   **Quality Perspectives (QP)**:
+08. **Quality Perspectives (QP)**:
     How the Non-Functional Requirements (NR) are addressed.
 
+09. **Decision Record (DR)**:
+    The major decisions related to the architecture, each recording the
+    forces at play, the chosen response, and the reasoning that justifies it.
+
+The **Artifact**s have the following cross-references:
+
+```text
+ARCH-02-FV Functionality View   ──(depends on)─► ARCH-02-FV Functionality View
+ARCH-03-IV Information View     ──(entity)─►     SPEC-05-DM Data Model
+ARCH-03-IV Information View     ──(owner)─►      ARCH-02-FV Functionality View
+ARCH-04-CO Concurrency View     ──(hosts)─►      ARCH-02-FV Functionality View
+ARCH-06-DP Deployment View      ──(hosts)─►      ARCH-02-FV Functionality View
+ARCH-07-OV Operations View      ──(element)─►    ARCH-02-FV Functionality View
+ARCH-07-OV Operations View      ──(element)─►    ARCH-06-DP Deployment View
+ARCH-08-QP Quality Perspectives ──(addresses)─►  SPEC-04-NR Non-Functional Requirements
+ARCH-08-QP Quality Perspectives ──(affects)─►    ARCH-02-FV Functionality View
+ARCH-08-QP Quality Perspectives ──(affects)─►    ARCH-06-DP Deployment View
+ARCH-09-DR Decision Record      ──(affects)─►    ARCH-02-FV Functionality View
+ARCH-09-DR Decision Record      ──(affects)─►    ARCH-06-DP Deployment View
+```
+
 Context View (CV)
 -----------------
 
@@ -87,15 +117,15 @@ and boundaries.
 
     <format>
 
-    ##  ENTITY ARCH-CV-<arch-cv-entity-id/>: <arch-cv-entity-name/>
+    ##  ENTITY: <arch-cv-entity-name/> <a id="ARCH-CV-<arch-cv-entity-id/>"></a>
 
     -   Kind:      <arch-cv-entity-kind/>
     -   Direction: <arch-cv-entity-direction/>
     -   Interface: <arch-cv-entity-interface/>
     -   Data:      <arch-cv-entity-data/>
 
-    <arch-cv-entity-description/>
-    (why: <arch-cv-entity-rationale/>)
+    <arch-cv-entity-description/>,
+    **BECAUSE** <arch-cv-entity-rationale/>.
 
     </format>
 
@@ -117,7 +147,7 @@ and boundaries.
         -   `Service`:      A third-party or managed service the solution consumes.
         -   `Datastore`:    An external data repository the solution reads from or writes to.
         -   `Device`:       A physical device or sensor the solution communicates with.
-        -   `Organization`: An external organizational party (e.g. regulator, vendor).
+        -   `Organization`: An external organizational party.
 
     -   <arch-cv-entity-direction/> is the flow of interaction relative to
         the solution: `Inbound` (entity drives the solution), `Outbound`
@@ -137,12 +167,12 @@ and boundaries.
         for the entity being part of the system context.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Functionality View (FV)
 -----------------------
 
-The functional elements of the solution, their responsibilities,
+The functional components of the solution, their responsibilities,
 interfaces, and primary interactions, describing *what* the system does
 at runtime.
 
@@ -155,69 +185,68 @@ at runtime.
     ✳   Created:  **<timestamp-created/>**
     ✎   Modified: **<timestamp-modified/>**
 
-    <arch-fv-element/>
-    <arch-fv-element/>
+    <arch-fv-component/>
+    <arch-fv-component/>
     [...]
 
     </format>
 
--   <arch-fv-element/> format:
+-   <arch-fv-component/> format:
 
     <format>
 
-    ##  ELEMENT ARCH-FV-<arch-fv-element-id/>: <arch-fv-element-name/>
+    ##  COMPONENT: <arch-fv-component-name/> <a id="ARCH-FV-<arch-fv-component-id/>"></a>
 
-    -   Kind:           <arch-fv-element-kind/>
-    -   Responsibility: <arch-fv-element-responsibility/>
-    -   Interface:      <arch-fv-element-interface/>
-    -   Depends On:     <arch-fv-element-dependency/>, [...]
+    -   Kind:           <arch-fv-component-kind/>
+    -   Responsibility: <arch-fv-component-responsibility/>
+    -   Interface:      <arch-fv-component-interface/>
+    -   Depends On:     <arch-fv-component-dependency/>, [...]
 
-    <arch-fv-element-description/>
-    (why: <arch-fv-element-rationale/>)
+    <arch-fv-component-description/>,
+    **BECAUSE** <arch-fv-component-rationale/>.
 
     </format>
 
--   <arch-fv-element/> details:
+-   <arch-fv-component/> details:
 
-    -   <arch-fv-element-id/>: per-artifact unique "slug" of always 1-3
+    -   <arch-fv-component-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
-        <arch-fv-element-name/>.
+        <arch-fv-component-name/>.
 
-    -   <arch-fv-element-name/> is a short (2-5 word) summary of the
-        functional element (e.g. `Authentication Service`, `Order
+    -   <arch-fv-component-name/> is a short (2-5 word) summary of the
+        functional component (e.g. `Authentication Service`, `Order
         Processor`, `Notification Dispatcher`).
 
-    -   <arch-fv-element-kind/> is one of:
-
-        -   `Component`:  A cohesive unit of functionality with a defined interface.
-        -   `Service`:    An independently deployable provider of functionality.
-        -   `Module`:     A logical grouping of related functionality within a component.
-        -   `Connector`:  A mediator that conveys interactions between elements (e.g. bus, gateway).
-        -   `Subsystem`:  A larger composite grouping several components.
+    -   <arch-fv-component-kind/> is one of:
+        -   `Component`: Cohesive unit of functionality with a defined interface.
+        -   `Service`:   Independently deployable provider of functionality.
+        -   `Module`:    Logical grouping of related functionality within a component.
+        -   `Connector`: Mediator that conveys interactions between components (e.g. bus, gateway).
+        -   `Subsystem`: Larger composite grouping several components.
 
-    -   <arch-fv-element-responsibility/> is the 1-sentence statement of
-        the single, primary responsibility the element owns.
+    -   <arch-fv-component-responsibility/> is the 1-sentence statement of
+        the single, primary responsibility the component owns.
 
-    -   <arch-fv-element-interface/> is how other elements interact with
-        this element (e.g. REST API, library API, message topic, CLI).
+    -   <arch-fv-component-interface/> is how other components interact with
+        this component (e.g. REST API, library API, message topic, CLI).
 
-    -   <arch-fv-element-dependency/> is an `ARCH-FV-<arch-fv-element-id/>`
-        reference to another functional element this element depends on
+    -   <arch-fv-component-dependency/> is an `ARCH-FV-<arch-fv-component-id/>`
+        reference to another functional component this component depends on
         at runtime.
 
-    -   <arch-fv-element-description/> is a concise paragraph (1-3
-        sentences) of prose describing *what* the element does and how it
-        collaborates with the elements it depends on.
+    -   <arch-fv-component-description/> is a concise paragraph (1-3
+        sentences) of prose describing *what* the component does and how it
+        collaborates with the components it depends on.
 
-    -   <arch-fv-element-rationale/> is the 1-sentence rationale ("why")
-        for the element's existence and boundary.
+    -   <arch-fv-component-rationale/> is the 1-sentence rationale ("why")
+        for the component's existence and boundary.
 
-    -   In case an element has no dependencies at all, the
+    -   In case a component has no dependencies at all, the
         entire `- Depends On:` bullet point is omitted.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Information View (IV)
 ---------------------
@@ -245,15 +274,15 @@ flow.
 
     <format>
 
-    ##  ASPECT ARCH-IV-<arch-iv-aspect-id/>: <arch-iv-aspect-name/>
+    ##  ASPECT: <arch-iv-aspect-name/> <a id="ARCH-IV-<arch-iv-aspect-id/>"></a>
 
     -   Concern:    <arch-iv-aspect-concern/>
     -   Entities:   <arch-iv-aspect-entity/>, [...]
     -   Owner:      <arch-iv-aspect-owner/>
     -   Lifecycle:  <arch-iv-aspect-lifecycle/>
 
-    <arch-iv-aspect-description/>
-    (why: <arch-iv-aspect-rationale/>)
+    <arch-iv-aspect-description/>,
+    **BECAUSE** <arch-iv-aspect-rationale/>.
 
     </format>
 
@@ -277,8 +306,8 @@ flow.
         reference to a corresponding entity of the Data Model **Artifact**
         the aspect governs.
 
-    -   <arch-iv-aspect-owner/> is an `ARCH-FV-<arch-fv-element-id/>`
-        reference to the functional element that owns this information.
+    -   <arch-iv-aspect-owner/> is an `ARCH-FV-<arch-fv-component-id/>`
+        reference to the functional component that owns this information.
 
     -   <arch-iv-aspect-lifecycle/> is how the information comes into
         being, changes, and is disposed of (e.g. `created on order,
@@ -295,12 +324,12 @@ flow.
         respective bullet point is omitted.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Concurrency View (CO)
 ---------------------
 
-The concurrency structure of the solution, mapping functional elements
+The concurrency structure of the solution, mapping functional components
 to processes and threads, and defining how they coordinate and
 communicate.
 
@@ -323,15 +352,15 @@ communicate.
 
     <format>
 
-    ##  UNIT ARCH-CO-<arch-co-unit-id/>: <arch-co-unit-name/>
+    ##  UNIT: <arch-co-unit-name/> <a id="ARCH-CO-<arch-co-unit-id/>"></a>
 
     -   Kind:         <arch-co-unit-kind/>
     -   Hosts:        <arch-co-unit-element/>, [...]
     -   Multiplicity: <arch-co-unit-multiplicity/>
     -   Coordination: <arch-co-unit-coordination/>
 
-    <arch-co-unit-description/>
-    (why: <arch-co-unit-rationale/>)
+    <arch-co-unit-description/>,
+    **BECAUSE** <arch-co-unit-rationale/>.
 
     </format>
 
@@ -348,14 +377,14 @@ communicate.
 
     -   <arch-co-unit-kind/> is one of:
 
-        -   `Process`:    An independent OS process with its own address space.
-        -   `Thread`:     A thread of execution within a process.
-        -   `Pool`:       A managed group of interchangeable workers.
-        -   `Queue`:      An asynchronous buffer decoupling producers and consumers.
-        -   `EventLoop`:  A single-threaded cooperative scheduler of tasks.
+        -   `Process`:   An independent OS process with its own address space.
+        -   `Thread`:    A thread of execution within a process.
+        -   `Pool`:      A managed group of interchangeable workers.
+        -   `Queue`:     An asynchronous buffer decoupling producers and consumers.
+        -   `EventLoop`: A single-threaded cooperative scheduler of tasks.
 
-    -   <arch-co-unit-element/> is an `ARCH-FV-<arch-fv-element-id/>`
-        reference to a functional element that runs inside this
+    -   <arch-co-unit-element/> is an `ARCH-FV-<arch-fv-component-id/>`
+        reference to a functional component that runs inside this
         concurrency unit.
 
     -   <arch-co-unit-multiplicity/> is how many instances of the unit run
@@ -372,11 +401,11 @@ communicate.
     -   <arch-co-unit-rationale/> is the 1-sentence rationale ("why") for
         the chosen concurrency structure.
 
-    -   In case the unit hosts no functional elements, the
+    -   In case the unit hosts no functional components, the
         entire `- Hosts:` bullet point is omitted.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Development View (DV)
 ---------------------
@@ -403,12 +432,12 @@ the module organization, build approach, and codeline conventions.
 
     <format>
 
-    ##  ASPECT ARCH-DV-<arch-dv-aspect-id/>: <arch-dv-aspect-name/>
+    ##  ASPECT: <arch-dv-aspect-name/> <a id="ARCH-DV-<arch-dv-aspect-id/>"></a>
 
     -   Category: <arch-dv-aspect-category/>
 
-    <arch-dv-aspect-description/>
-    (why: <arch-dv-aspect-rationale/>)
+    <arch-dv-aspect-description/>,
+    **BECAUSE** <arch-dv-aspect-rationale/>.
 
     </format>
 
@@ -438,7 +467,7 @@ the module organization, build approach, and codeline conventions.
         for the development aspect.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Deployment View (DP)
 --------------------
@@ -465,15 +494,15 @@ elements to the runtime platform, hardware, and network topology.
 
     <format>
 
-    ##  NODE ARCH-DP-<arch-dp-node-id/>: <arch-dp-node-name/>
+    ##  NODE: <arch-dp-node-name/> <a id="ARCH-DP-<arch-dp-node-id/>"></a>
 
     -   Kind:     <arch-dp-node-kind/>
     -   Platform: <arch-dp-node-platform/>
     -   Hosts:    <arch-dp-node-element/>, [...]
     -   Network:  <arch-dp-node-network/>
 
-    <arch-dp-node-description/>
-    (why: <arch-dp-node-rationale/>)
+    <arch-dp-node-description/>,
+    **BECAUSE** <arch-dp-node-rationale/>.
 
     </format>
 
@@ -489,18 +518,18 @@ elements to the runtime platform, hardware, and network topology.
 
     -   <arch-dp-node-kind/> is one of:
 
-        -   `Server`:     A physical or virtual machine.
-        -   `Container`:  A containerized runtime (e.g. Docker, OCI).
-        -   `Cluster`:    A managed group of nodes (e.g. Kubernetes cluster).
-        -   `Function`:   A serverless / function-as-a-service runtime.
-        -   `Device`:     An edge or client device.
-        -   `Managed`:    A managed cloud service (e.g. managed database, queue).
+        -   `Server`:    A physical or virtual machine.
+        -   `Container`: A containerized runtime (e.g. Docker, OCI).
+        -   `Cluster`:   A managed group of nodes (e.g. Kubernetes cluster).
+        -   `Function`:  A serverless / function-as-a-service runtime.
+        -   `Device`:    An edge or client device.
+        -   `Managed`:   A managed cloud service (e.g. managed database, queue).
 
     -   <arch-dp-node-platform/> is the runtime platform of the node
         (e.g. `Linux x86-64`, `Kubernetes 1.30`, `AWS Lambda (Node.js)`).
 
-    -   <arch-dp-node-element/> is an `ARCH-FV-<arch-fv-element-id/>`
-        reference to a functional element deployed onto this node.
+    -   <arch-dp-node-element/> is an `ARCH-FV-<arch-fv-component-id/>`
+        reference to a functional component deployed onto this node.
 
     -   <arch-dp-node-network/> is the network placement and connectivity
         of the node (e.g. `public subnet, TLS 443`, `private VLAN`).
@@ -512,11 +541,11 @@ elements to the runtime platform, hardware, and network topology.
     -   <arch-dp-node-rationale/> is the 1-sentence rationale ("why") for
         the node's placement and platform choice.
 
-    -   In case the node hosts no functional elements, the
+    -   In case the node hosts no functional components, the
         entire `- Hosts:` bullet point is omitted.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Operations View (OV)
 --------------------
@@ -543,13 +572,13 @@ production, defining installation, monitoring, and management concerns.
 
     <format>
 
-    ##  CONCERN ARCH-OV-<arch-ov-concern-id/>: <arch-ov-concern-name/>
+    ##  CONCERN: <arch-ov-concern-name/> <a id="ARCH-OV-<arch-ov-concern-id/>"></a>
 
     -   Category: <arch-ov-concern-category/>
     -   Element:  <arch-ov-concern-element/>, [...]
 
-    <arch-ov-concern-description/>
-    (why: <arch-ov-concern-rationale/>)
+    <arch-ov-concern-description/>,
+    **BECAUSE** <arch-ov-concern-rationale/>.
 
     </format>
 
@@ -569,7 +598,7 @@ production, defining installation, monitoring, and management concerns.
         `Monitoring`, `Logging`, `Alerting`, `Backup`, `Recovery`,
         `Upgrade`, or `Support`.
 
-    -   <arch-ov-concern-element/> is an `ARCH-FV-<arch-fv-element-id/>`
+    -   <arch-ov-concern-element/> is an `ARCH-FV-<arch-fv-component-id/>`
         or `ARCH-DP-<arch-dp-node-id/>` reference to the functional
         element or deployment node the concern applies to.
 
@@ -584,7 +613,7 @@ production, defining installation, monitoring, and management concerns.
         entire `- Element:` bullet point is omitted.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
 
 Quality Perspectives (QP)
 -------------------------
@@ -610,15 +639,15 @@ How the Non-Functional Requirements (NR) are addressed.
 
     <format>
 
-    ##  PERSPECTIVE ARCH-QP-<arch-qp-perspective-id/>: <arch-qp-perspective-name/>
+    ##  PERSPECTIVE: <arch-qp-perspective-name/> <a id="ARCH-QP-<arch-qp-perspective-id/>"></a>
 
     -   Quality:    <arch-qp-perspective-quality/>
     -   Addresses:  <arch-qp-perspective-requirement/>, [...]
     -   Tactic:     <arch-qp-perspective-tactic/>
     -   Affects:    <arch-qp-perspective-element/>, [...]
 
-    <arch-qp-perspective-description/>
-    (why: <arch-qp-perspective-rationale/>)
+    <arch-qp-perspective-description/>,
+    **BECAUSE** <arch-qp-perspective-rationale/>.
 
     </format>
 
@@ -649,7 +678,7 @@ How the Non-Functional Requirements (NR) are addressed.
         replication behind a load balancer`, `read-through cache`, `circuit
         breaker`).
 
-    -   <arch-qp-perspective-element/> is an `ARCH-FV-<arch-fv-element-id/>`
+    -   <arch-qp-perspective-element/> is an `ARCH-FV-<arch-fv-component-id/>`
         or `ARCH-DP-<arch-dp-node-id/>` reference to the functional
         element or deployment node the tactic affects.
 
@@ -664,4 +693,190 @@ How the Non-Functional Requirements (NR) are addressed.
         entire `- Affects:` bullet point is omitted.
 
     -   In case the rationale is not present, the
-        entire `(why: [...])` chunk is omitted.
+        entire `, **BECAUSE** [...]` clause is omitted.
+
+Decision Record (DR)
+--------------------
+
+The major decisions related to the architecture, each recording the
+forces at play, the chosen response, and the reasoning that justifies it.
+
+-   Format:
+
+    <format>
+
+    #   ARCHITECTURE: DECISION RECORD (ARCH-DR)
+
+    ✳   Created:  **<timestamp-created/>**
+    ✎   Modified: **<timestamp-modified/>**
+
+    <arch-dr-decision/>
+    <arch-dr-decision/>
+    [...]
+
+    </format>
+
+-   <arch-dr-decision/> format:
+
+    <format>
+
+    ##  DECISION: <arch-dr-decision-name/> <a id="ARCH-DR-<arch-dr-decision-id/>"></a>
+
+    -   Status:    <arch-dr-decision-status/>
+    -   Affects:   <arch-dr-decision-element/>, [...]
+    -   Created:   <arch-dr-decision-created/>
+    -   Modified:  <arch-dr-decision-modified/>
+
+    -   WHEN (Context):
+        <arch-dr-decision-context/>
+
+    -   WHAT (Decision):
+        <arch-dr-decision-decision/>
+
+    -   WHY (Rationale):
+        <arch-dr-decision-rationale/>
+
+    -   NOTES (Background):
+        <arch-dr-decision-notes/>
+
+    </format>
+
+-   <arch-dr-decision/> details:
+
+    -   <arch-dr-decision-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
+        <arch-dr-decision-name/>.
+
+    -   <arch-dr-decision-name/> is a short summary of the
+        <arch-dr-decision-decision/>, not longer than 80 characters.
+
+    -   <arch-dr-decision-status/> is one of `proposed`, `accepted`,
+        `deprecated`, or `superseded by ARCH-DR-<arch-dr-decision-id/>`.
+
+    -   <arch-dr-decision-element/> is an `ARCH-FV-<arch-fv-component-id/>`
+        or `ARCH-DP-<arch-dp-node-id/>` reference to the functional
+        element or deployment node the decision affects.
+
+    -   <arch-dr-decision-created/> is the timestamp when this decision was
+        created, and <arch-dr-decision-modified/> is the timestamp when
+        this decision was last modified, both in the same ISO-style format
+        as the **Artifact**'s own timestamps.
+
+    -   <arch-dr-decision-context/> captures the situation that forces the
+        decision - the "why are we even talking about this" part. It
+        describes the situation as it is, before the decision is made. The
+        following usually goes into it: the problem or need (what's broken,
+        missing, or about to change that requires a decision); the forces at
+        play (technical constraints, business requirements, deadlines, team
+        skills, existing systems, regulatory/compliance pressures - often
+        competing, and that tension is the whole point); relevant facts
+        (current architecture, prior decisions, assumptions, what's known
+        and what's uncertain); and scope/boundaries (what this decision is
+        and isn't about). It is written neutrally and factually. It should
+        not contain the decision itself, nor advocate for an option - a
+        reader should be able to read it, pause, and arrive at the decision
+        themselves because the forces make it (nearly) inevitable.
+
+    -   <arch-dr-decision-decision/> states what is actually going to be
+        done - the chosen response to the forces laid out in the context. It
+        is written in active, assertive voice, in the present or imperative
+        tense, as a committed position rather than a discussion. The
+        following usually goes into it: the choice itself (clearly and
+        unambiguously) and the essence of how (enough of the approach to
+        make the choice concrete - the mechanism, pattern, or technology -
+        but not a full implementation specification). It is a declaration,
+        not a deliberation, usually using the wording "We use..." or "We
+        do...", active, definite, owning the choice. Avoid hedging ("we
+        might", "we could consider") - the deliberation already happened,
+        the decision records the verdict.
+
+    -   <arch-dr-decision-rationale/> is the reasoning that justifies the
+        decision - the bridge that explains why this choice, given those
+        forces. It answers "Of all the things we could have done, why was
+        this the right one?". Where the context states the forces and the
+        decision states the choice, the rationale is the logical connective
+        tissue between them - it shows that the decision actually follows
+        from the context. The following usually goes into it: the deciding
+        factors (which forces from the context carried the most weight, and
+        how the chosen option satisfies them best); the trade-off reasoning
+        (what was optimized for and what was knowingly sacrificed - naming
+        the trade-off is the heart of rationale); why the alternatives lost
+        (the comparative argument: "option B failed on X, option C cost too
+        much on Y"); and assumptions and evidence (benchmarks, prior
+        experience, constraints, or principles the reasoning rests on).
+
+    -   <arch-dr-decision-notes/> is *OPTIONAL* and can be omitted when it
+        does not add genuine value - most decisions won't need it. The
+        following usually goes into it: information of the decision *process*
+        (e.g. a weighted decision matrix of considered alternatives);
+        consequences of the decision (but only when non-obvious downstream
+        effects need to be called out); and links to strongly related
+        decisions.
+
+    -   <arch-dr-decision-context/>, <arch-dr-decision-decision/>, and
+        <arch-dr-decision-rationale/> 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 in recording *that* a decision
+        was made and *why* - not in filling out sections of a document.
+
+    -   For the relationship between context, decision, and rationale, good
+        checks are: the "litmus test" is that context = forces, decision =
+        response to those forces, rationale = why the decision answers the
+        forces in the context. The decision should feel like the natural,
+        almost inevitable answer to the context - if a reader is surprised
+        by the decision, either the context is missing a force, or the
+        decision is under-justified. The rationale should make the decision
+        feel earned, not asserted - if you would delete the rationale and
+        the decision suddenly looks arbitrary, the rationale was doing its
+        job.
+
+    -   In case the element reference is not present, the
+        entire `- Affects:` bullet point is omitted.
+
+    -   In case the `NOTES (Background)` content is not present, the
+        entire `NOTES (Background)` chunk is omitted.
+
+-   A decision *MUST* qualify on all of the following three tenets:
+
+    -   **Hard to Reverse**: the cost of changing it later is meaningful
+        ("Oh my god, this would result in a dramatic refactoring!"). So,
+        if a decision is easy to reverse, just skip it.
+
+    -   **Surprising without Context**: a future architect will look at
+        the code and wonder ("Why on earth did they do it this way?").
+        So, if a decision is not surprising, nobody will wonder why.
+
+    -   **Result of a Real Trade-Off**: there were genuine alternatives
+        and one was picked for specific reasons ("We deliberately chose
+        this, because..."). So, if there was no real alternative,
+        there's nothing to record beyond "we did the obvious thing."
+
+-   The following typically qualify as a decision:
+
+    -   **Architectural shape.** "We're using a monorepo." "The write
+        model is event-sourced, the read model is projected into PostgreSQL."
+
+    -   **Integration patterns between contexts.** "Ordering and Billing
+        communicate via domain events, not synchronous HTTP."
+
+    -   **Technology choices that carry lock-in.** Database, message bus,
+        auth provider, deployment target. Not every library - just the
+        ones that would take a quarter to swap out.
+
+    -   **Boundary and scope decisions.** "Customer data is owned by the
+        Customer context; other contexts reference it by ID only." The explicit
+        no-s are as valuable as the yes-s.
+
+    -   **Deliberate deviations from the obvious path.** "We're using
+        manual SQL instead of an ORM because X." Anything where a reasonable
+        reader would assume the opposite. These stop the next engineer from
+        "fixing" something that was deliberate.
+
+    -   **Constraints not visible in the code.** "We can't use AWS because
+        of compliance requirements." "Response times must be under 200ms because
+        of the partner API contract."
+
+    -   **Rejected alternatives when the rejection is non-obvious.** If
+        you considered GraphQL and picked REST for subtle reasons, record it -
+        otherwise someone will suggest GraphQL again in six months.