archsight 0.3.1 → 0.3.2

data/lib/archsight/linter.rb

@@ -26,6 +26,12 @@ module Archsight
       @errors
     end
 
+    # Things that still work but should be changed: renamed kinds and relation keys that the files still use.
+    # They are not errors, so they do not make `archsight lint` fail.
+    def warnings
+      @database.respond_to?(:deprecations) ? @database.deprecations.map(&:to_s) : []
+    end
+
     private
 
     # Pages need exactly one menu and their [[links]] must resolve

data/lib/archsight/mcp/analyze_resource_tool.rb

@@ -24,13 +24,13 @@ class Archsight::MCP::AnalyzeResourceTool < FastMcp::Tool
        Example: kind="ApplicationInterface", name="Kubernetes:RestAPI", impact=true
 
     RESOURCE KINDS: TechnologyArtifact, ApplicationComponent, ApplicationInterface,
-    ApplicationService, BusinessRequirement, ComplianceEvidence, and more.
+    ApplicationService, MotivationRequirement, ComplianceEvidence, and more.
   DESC
   arguments do
     required(:kind).filled(:string).description(
       "Resource type to analyze. Common kinds: TechnologyArtifact (repos, code), " \
       "ApplicationComponent (services), ApplicationInterface (APIs), " \
-      "BusinessRequirement (compliance controls), ComplianceEvidence (compliance proof)"
+      "MotivationRequirement (compliance and legal requirements), ComplianceEvidence (compliance proof)"
     )
     required(:name).filled(:string).description(
       "Exact name of the resource (case-sensitive). Use QueryTool first if unsure of exact name."

data/lib/archsight/mcp/resource_doc_tool.rb

@@ -23,7 +23,7 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
     • ApplicationComponent - Services and application building blocks
     • ApplicationInterface - APIs and interfaces exposed by components
     • ApplicationService - Business services provided by applications
-    • BusinessRequirement - Compliance controls and business requirements
+    • MotivationRequirement - Statements of need, such as compliance and legal requirements
     • ComplianceEvidence - Evidence linking artifacts to compliance requirements
   DESC
   arguments do
@@ -61,7 +61,7 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
         kind: kind_symbol.to_s,
         description: klass.description || "No description available",
         annotation_count: klass.annotations.count,
-        relation_count: klass.relations.count
+        relation_count: klass.declared_relations.count
       }
     end
 

data/lib/archsight/query/ast.rb

@@ -218,7 +218,8 @@ module Archsight::Query::AST
     attr_reader :kind_name
 
     def initialize(kind_name)
-      @kind_name = kind_name
+      # a renamed kind keeps matching under its old name
+      @kind_name = Archsight::Resources.canonical(kind_name)
     end
   end
 

data/lib/archsight/query/evaluator.rb

@@ -292,7 +292,7 @@ class Archsight::Query::Evaluator
 
     case node.operator
     when "=="
-      instance_kind == node.value.value.to_s
+      instance_kind == Archsight::Resources.canonical(node.value.value)
     when "=~"
       regex = build_regex_from_value(node.value)
       !!(instance_kind =~ regex)
@@ -303,7 +303,7 @@ class Archsight::Query::Evaluator
 
   def evaluate_kind_in_condition(node, instance)
     instance_kind = instance.class.to_s.split("::").last
-    query_values = node.values.map { |v| v.value.to_s }
+    query_values = node.values.map { |v| Archsight::Resources.canonical(v.value) }
     query_values.include?(instance_kind)
   end
 

data/lib/archsight/references.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Archsight
+  # References derives relations from what the text and the diagrams of resources say, so that nobody has to repeat in
+  # YAML what is already written:
+  #
+  # - `mentions`: `[[Target]]`, `[[Kind/Name]]` and `![[View/Name]]` in a markdown text (a page's content, the
+  #   description of any resource, any annotation a kind defines as markdown)
+  # - `depicts`: the `resource "..."` of the nodes of a diagram: an ```asd block in such a text, an `.asd` file embedded
+  #   with `![](file.asd)`, and the `architecture/diagram` annotation of any resource
+  #
+  # The relations are added to the resources like written ones (see Base#add_derived_relation), after the written ones
+  # are resolved, and are rebuilt on every load. Only what names a resource exactly counts: a target that is missing,
+  # ambiguous or only matches part of a name is skipped (the linter reports the broken ones), and so are links in code.
+  # Views and requirements blocks select resources with a query when they run, so they name nothing.
+  module References
+    # A fenced code block, and an inline code span: links in them are shown as written
+    FENCE = /^[ \t]*(?:```|~~~).*?^[ \t]*(?:```|~~~)[ \t]*$/m
+    INLINE_CODE = /`[^`\n]*`/
+
+    # Annotations that are markdown besides those a kind defines with `format: :markdown`
+    MARKDOWN_KEYS = %w[page/content architecture/description].freeze
+
+    module_function
+
+    # Adds the derived relations to every resource of the database.
+    def derive!(database)
+      finder = Finder.new(database)
+      database.instances.values.flat_map(&:values).each do |inst|
+        text_sources(inst).each { |markdown| mentions(markdown, finder).each { |target| link(inst, :mentions, target) } }
+        diagram_sources(inst, database).each { |source| depictions(source, finder).each { |target| link(inst, :depicts, target) } }
+      end
+    end
+
+    # The resources a markdown text mentions with `[[...]]` links and `![[View/...]]` embeds, outside code.
+    # @return [Array<Base>]
+    def mentions(markdown, finder)
+      visible = markdown.to_s.gsub(FENCE, "").gsub(INLINE_CODE, "")
+      embeds = visible.scan(Helpers::Embeds::PATTERN).flatten.map(&:strip).filter_map { |reference| finder.embed(reference) }
+      targets = visible.gsub(Helpers::Embeds::PATTERN, "").scan(Helpers::WikiLinks::PATTERN).map { |match| match.first.strip }
+      (embeds + targets.filter_map { |target| finder.link(target) }).uniq
+    end
+
+    # The resources the nodes of a diagram source name with `resource "..."`; a source that is not a valid diagram
+    # names none.
+    # @return [Array<Base>]
+    def depictions(source, finder)
+      Diagram.resource_references(source).filter_map { |reference| finder.reference(reference) }
+    rescue Diagram::Error
+      []
+    end
+
+    # The markdown texts of a resource: a page's content, the description, and every annotation its kind defines as
+    # markdown.
+    def text_sources(inst)
+      inst.annotations.filter_map do |key, value|
+        value if value.is_a?(String) && value.include?("[[") && markdown_annotation?(inst, key)
+      end
+    end
+
+    # The diagram sources of a resource: ```asd blocks and embedded `.asd` files of its markdown texts, and its
+    # annotations that are diagrams (`architecture/diagram`).
+    def diagram_sources(inst, database)
+      sources = [] #: Array[String]
+      inst.annotations.each do |key, value|
+        next unless value.is_a?(String)
+
+        if inst.class.annotation_format(key) == :asd
+          sources << value
+        elsif markdown_annotation?(inst, key)
+          sources.concat(Helpers::DiagramBlocks.sources(value))
+          sources.concat(embedded_diagrams(inst, value, database)) if value.include?(".asd")
+        end
+      end
+      sources
+    end
+
+    def markdown_annotation?(inst, key)
+      MARKDOWN_KEYS.include?(key) || inst.class.annotation_format(key) == :markdown
+    end
+
+    # The sources of the `.asd` files a markdown text embeds, found next to the file the resource comes from
+    def embedded_diagrams(inst, markdown, database)
+      resources_dir = database.path.to_s
+      base_dir = Assets.base_dir_for(inst, resources_dir: resources_dir)
+      return [] unless base_dir
+
+      Helpers::AssetImages.asd_files(markdown, base_dir: base_dir, resources_dir: resources_dir).filter_map do |_path, file|
+        File.read(file) if File.size(file) <= Helpers::AssetImages::MAX_ASD
+      end
+    rescue SystemCallError
+      []
+    end
+
+    def link(inst, verb, target)
+      return if target.equal?(inst)
+
+      inst.add_derived_relation(verb, target)
+    end
+
+    # Finds the resource a reference in a text names, exactly (see WikiLinks#exact_target_for)
+    class Finder
+      def initialize(database)
+        @database = database
+        @resolver = Helpers::ResourceResolver.new(database)
+        @links = Helpers::WikiLinks.new(database, resolver: @resolver)
+      end
+
+      # A `[[...]]` target: a page by name or title, `Kind/Name`, or a resource name
+      def link(target)
+        @links.exact_target_for(target)
+      end
+
+      # An `![[Kind/Name]]` embed: only views and analyses can be embedded
+      def embed(reference)
+        kind = reference.split("/", 2).first
+        return unless Helpers::Embeds::KINDS.include?(kind)
+
+        reference(reference)
+      end
+
+      # A `resource "..."` of a diagram or an embed: `Name` across all kinds, or `Kind/Name`
+      def reference(reference)
+        found = @resolver.find(reference)
+        found.is_a?(Array) ? @database.instances_by_kind(found.first)[found.last] : nil
+      end
+    end
+  end
+end

data/lib/archsight/requirements.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Archsight
-  # The business requirements of a selection of resources, as the "Business Requirements" table of an instance page
-  # shows them, merged over all resources of the selection: one entry per BusinessRequirement, with the status the
+  # The requirements of a selection of resources, as the "Requirements" table of an instance page
+  # shows them, merged over all resources of the selection: one entry per MotivationRequirement, with the status the
   # resources give it (`realizes` = implemented, `partiallyRealizes` = partial, `plans` = planned).
   #
   #   Requirements.collect(db, of: 'ApplicationService: name =~ "Backup"', priority: ["must"])
@@ -12,7 +12,7 @@ module Archsight
     # Relation verb -> status, best first
     STATUSES = { "realizes" => "implemented", "partiallyRealizes" => "partial", "plans" => "planned" }.freeze
     PRIORITIES = %w[must should may].freeze
-    RELATION = :businessRequirements
+    RELATION = :motivationRequirements
 
     module_function
 
@@ -52,7 +52,7 @@ module Archsight
         row << cell.new(text: e[:by].map { |b| b[:name] }.join("\n")) if with_by
         row
       end
-      ViewTable::Table.new(title: spec[:title].to_s.empty? ? "Business Requirements" : spec[:title],
+      ViewTable::Table.new(title: spec[:title].to_s.empty? ? "Requirements" : spec[:title],
                            columns: ["Status", "Name", "Priority", "Story", ("Realized by" if with_by)].compact, rows: rows, total: entries.length)
     end
 

data/lib/archsight/resources/application_component.rb

@@ -346,4 +346,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/application_interface.rb

@@ -47,6 +47,6 @@ class Archsight::Resources::ApplicationInterface < Archsight::Resources::Base
              enum: ["none", "hard coded", "pbac", "abac", "rbac"]
 
   relation :servedBy, :technologyComponents, :TechnologyInterface
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :serves, :dataObjects, :DataObject
 end

data/lib/archsight/resources/application_service.rb

@@ -214,10 +214,10 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   relation :realizedThrough, :applicationComponents, :ApplicationComponent
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
-  relation :partiallyRealizes, :businessRequirements, :BusinessRequirement
-  relation :plans, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
   relation :realizes, :dataObjects, :DataObject
   relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/base.rb

@@ -15,12 +15,21 @@ module Archsight
       end
 
       def self.relation(verb, kind, klass_name)
-        @relations ||= [] #: Array[[Symbol, Symbol, String]]
-        @relations << [verb, kind, klass_name]
+        @declared_relations ||= [] #: Array[[Symbol, Symbol, String]]
+        @declared_relations << [verb, kind, klass_name]
+        @relations = nil
       end
 
+      # The relations a resource of this kind may be written with in a file (`spec`)
+      def self.declared_relations
+        @declared_relations || []
+      end
+
+      # Every relation a resource of this kind can have: the declared ones and the derived ones (`mentions`,
+      # `depicts`, see Archsight::References). Everything that follows relations (queries, graphs, impact analysis)
+      # uses this; what lets a user write or choose relations uses declared_relations.
       def self.relations
-        @relations || []
+        @relations ||= (declared_relations + Archsight::Resources::DERIVED_RELATIONS).freeze
       end
 
       # A kind may mark at most this many annotations as summary (see Base.annotation)
@@ -111,6 +120,17 @@ module Archsight
         annotation_matching(key)&.format
       end
 
+      # The formats this kind defines for the given annotation keys, `{ "evidence/gaps" => "markdown" }` (keys without
+      # a format are left out). The frontend shows each value accordingly.
+      def self.annotation_formats(keys)
+        formats = {} #: Hash[String, String]
+        keys.each do |key|
+          format = annotation_format(key)
+          formats[key] = format.to_s if format
+        end
+        formats
+      end
+
       def self.annotation_enum(key)
         annotation_matching(key)&.enum
       end
@@ -231,17 +251,32 @@ module Archsight
       end
 
       def verb_allowed?(verb)
-        self.class.relations.any? { |v, _, _| v.to_s == verb.to_s }
+        self.class.declared_relations.any? { |v, _, _| v.to_s == verb.to_s }
       end
 
       def verb_kind_allowed?(verb, kind)
-        self.class.relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
+        self.class.declared_relations.any? { |v, k, _| v.to_s == verb.to_s && k.to_s == kind.to_s }
       end
 
       def relations(verb, kind)
         (spec[verb.to_s] || {})[kind.to_s] || []
       end
 
+      # Records a relation that is derived from this resource's text or diagram, not written in its file: the target
+      # goes into `spec` where the relations of this verb are read (so queries and graphs see it like any other) and
+      # learns about this resource as one that refers to it.
+      def add_derived_relation(verb, target)
+        key = Archsight::Resources::DERIVED_KEY.to_s
+        spec_root = (@raw["spec"] ||= {}) #: Hash[String, untyped]
+        by_key = (spec_root[verb.to_s] ||= {}) #: Hash[String, Array[Base]]
+        by_key[key] ||= [] #: Array[Base]
+        targets = by_key.fetch(key)
+        return if targets.any? { |known| known.equal?(target) }
+
+        targets << target
+        target.referenced_by(self, verb.to_sym)
+      end
+
       def set_relations(verb, kind, rels)
         spec[verb.to_s][kind.to_s] = rels
         rels.each { |rel| rel.referenced_by(self, verb) }

data/lib/archsight/resources/business_control.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# BusinessControl represents a control that guides a business process
+class Archsight::Resources::BusinessControl < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a control: a safeguard or decision step with an owner that guides how a business process is carried out.
+
+    ## ArchiMate / TOGAF Definition
+
+    **Layer:** Business
+    **Aspect:** Behavior (guidance)
+
+    ArchiMate has no control element. TOGAF's content metamodel has one: a decision-making step with
+    accountability and authority, applied to a process or function. A control is therefore modelled as
+    a business-layer kind that a `BusinessProcess` is guided by (`guidedBy`).
+
+    ## Usage
+
+    Use BusinessControl to represent:
+
+    - Security and compliance controls (access review, network documentation, backup verification)
+    - Operational checks that a process must pass (change approval, four-eyes principle)
+    - Controls of a standard or framework (BSI C5, ISO 27001, SOC 2), linked to the requirements they satisfy
+
+    ## How it connects
+
+    - A `BusinessProcess` is `guidedBy` the control
+    - The control is `ownedBy` the actor that is accountable for it and `executedBy` the actors that carry it out
+    - The control `satisfies` requirements and is `evidencedBy` compliance evidence
+
+    A control addresses requirements from the **process side**. Whether an application implements a requirement is
+    stated on the application (`realizes`, `plans`, `evidencedBy`), not on the control. Link evidence to a control
+    only for the records the control itself produces (reviews, diagrams, change history, audit logs), and set the
+    `evidence/type` of that evidence to `process`, `documentation` or `audit-log`.
+
+    Put the best practices and the evidence requirements of a control in the description.
+  MD
+
+  icon "shield-search"
+  layer "business"
+
+  annotation "control/id",
+             description: "Identifier of the control in its catalogue (e.g. COS-07)",
+             title: "Control ID",
+             summary: true
+
+  annotation "control/status",
+             description: "Implementation status of the control",
+             enum: %w[implemented partial planned not-implemented],
+             filter: :word,
+             summary: true
+
+  annotation "control/frequency",
+             description: "How often the control is carried out",
+             enum: %w[continuous event-based daily weekly monthly quarterly semi-annually annually],
+             filter: :word,
+             summary: true
+
+  annotation "control/objective",
+             description: "What the control achieves, in one short paragraph",
+             title: "Objective",
+             format: :markdown
+
+  annotation "control/last-review",
+             description: "When the control was last reviewed (ISO 8601 date or time)",
+             title: "Last review",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  annotation "control/next-review",
+             description: "When the control is due for review (ISO 8601 date or time)",
+             title: "Next review",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :executedBy, :businessActors, :BusinessActor
+  relation :satisfies, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
+end

data/lib/archsight/resources/business_process.rb

@@ -30,8 +30,9 @@ class Archsight::Resources::BusinessProcess < Archsight::Resources::Base
   icon "kanban-board"
   layer "business"
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :applicationServices, :ApplicationService
   relation :performedBy, :businessActors, :BusinessActor
+  relation :guidedBy, :businessControls, :BusinessControl
 end

data/lib/archsight/resources/business_product.rb

@@ -198,8 +198,8 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   end
 
   relation :realizes, :strategyCapabilities, :StrategyCapability
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :applicationServices, :ApplicationService
   relation :exposes, :applicationInterfaces, :ApplicationInterface

data/lib/archsight/resources/compliance_evidence.rb

@@ -25,6 +25,13 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
     - Test results and reports
     - Configuration documentation
     - Process documentation
+
+    ## Evidence of what
+
+    - **Of an application:** linked with `evidencedBy` from a service, component or technology element; it says how
+      that resource meets the requirement it `satisfies`
+    - **Of a control:** linked with `evidencedBy` from a `BusinessControl`; the records the control produces
+      (reviews, diagrams, change history, audit logs). Use `evidence/type` `process`, `documentation` or `audit-log`
   MD
 
   icon "shield-check"
@@ -40,5 +47,33 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
              enum: %w[implemented partial not-implemented],
              summary: true
 
-  relation :satisfies, :businessRequirements, :BusinessRequirement
+  # The structured answer to "how does the evidenced resource meet the requirement": one markdown field per
+  # question. `architecture/description` stays a short summary; the fields hold the detail.
+  annotation "evidence/mechanism",
+             description: "How the requirement is implemented: the concrete mechanism and where it lives " \
+                          "(code, chart, configuration), as a short markdown list",
+             format: :markdown
+
+  annotation "evidence/coverage",
+             description: "What the mechanism covers and what it does not (data, flows, tenants, environments)",
+             format: :markdown
+
+  annotation "evidence/operatorView",
+             description: "Whether the mechanism holds against operators (admins, platform staff) or only against " \
+                          "other tenants; names the privileged paths",
+             format: :markdown
+
+  annotation "evidence/verification",
+             description: "How effectiveness is verified: tests, audits, documents; says so when there are none",
+             format: :markdown
+
+  annotation "evidence/gaps",
+             description: "Remaining gaps and open questions, the most important first",
+             format: :markdown
+
+  annotation "evidence/sources",
+             description: "Where the statements come from: repositories and files, wiki pages, tickets",
+             format: :markdown
+
+  relation :satisfies, :motivationRequirements, :MotivationRequirement
 end

data/lib/archsight/resources/data_object.rb

@@ -46,5 +46,5 @@ class Archsight::Resources::DataObject < Archsight::Resources::Base
              title: "Schema Variants",
              sidebar: false
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
 end

data/lib/archsight/resources/{business_constraint.rb → motivation_constraint.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# BusinessConstraint represents restrictions or limitations on architecture
-class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
+# MotivationConstraint represents restrictions or limitations on architecture
+class Archsight::Resources::MotivationConstraint < Archsight::Resources::Base
   include_annotations :git, :architecture
 
   description <<~MD
@@ -18,7 +18,7 @@ class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
 
     ## Usage
 
-    Use BusinessConstraint to represent:
+    Use MotivationConstraint to represent:
 
     - Regulatory requirements (GDPR, SOX, PCI-DSS)
     - Security policies
@@ -28,5 +28,5 @@ class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
   MD
 
   icon "prohibition"
-  layer "business"
+  layer "motivation"
 end

data/lib/archsight/resources/motivation_goal.rb

@@ -33,5 +33,5 @@ class Archsight::Resources::MotivationGoal < Archsight::Resources::Base
 
   relation :realizes, :outcomes, :MotivationOutcome
   relation :refinedBy, :goals, :MotivationGoal
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationRequirements, :MotivationRequirement
 end

data/lib/archsight/resources/{business_requirement.rb → motivation_requirement.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# BusinessRequirement represents functional or non-functional requirements
-class Archsight::Resources::BusinessRequirement < Archsight::Resources::Base
+# MotivationRequirement represents functional or non-functional requirements
+class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
   include_annotations :git, :architecture
 
   description <<~MD
@@ -18,17 +18,27 @@ class Archsight::Resources::BusinessRequirement < Archsight::Resources::Base
 
     ## Usage
 
-    Use BusinessRequirement to represent:
+    Use MotivationRequirement to represent:
 
     - Compliance requirements (C5, ISO 27001)
     - Security requirements
     - Performance requirements
     - Functional specifications
     - Legal obligations (GDPR, NIS2)
+
+    ## Who addresses it
+
+    A requirement is where the process side and the application side meet:
+
+    - **Process side:** a `BusinessControl` `satisfies` the requirement; a process is `guidedBy` the control
+    - **Application side:** applications `realize` or `plan` the requirement and are `evidencedBy` `ComplianceEvidence`,
+      which `satisfies` it
+
+    Both show as incoming relations on the requirement's page.
   MD
 
   icon "task-list"
-  layer "business"
+  layer "motivation"
 
   annotation "requirement/type",
              description: "Type of requirement (business or legal)",
@@ -39,7 +49,7 @@ class Archsight::Resources::BusinessRequirement < Archsight::Resources::Base
              description: "Regulatory or standard reference (comma-separated for multiple)",
              filter: :list,
              enum: %w[c5-2020 itgs-2023 gdpr-2018 nis1 nis2 iso27001 sox pci-dss hipaa eu-data-act-2025 ens
-                      iso27001-2022],
+                      iso27001-2022 vsa-2023 con-11-1],
              summary: true
 
   annotation "requirement/priority",

data/lib/archsight/resources/motivation_stakeholder.rb

@@ -32,7 +32,7 @@ class Archsight::Resources::MotivationStakeholder < Archsight::Resources::Base
   layer "motivation"
 
   relation :hasConcern, :strategyCapabilities, :StrategyCapability
-  relation :hasConcern, :businessRequirements, :BusinessRequirement
-  relation :hasConcern, :businessConstraints, :BusinessConstraint
+  relation :hasConcern, :motivationRequirements, :MotivationRequirement
+  relation :hasConcern, :motivationConstraints, :MotivationConstraint
   relation :hasConcern, :goals, :MotivationGoal
 end

data/lib/archsight/resources/strategy_capability.rb

@@ -30,8 +30,8 @@ class Archsight::Resources::StrategyCapability < Archsight::Resources::Base
   icon "strategy"
   layer "strategy"
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :applicationServices, :ApplicationService
   relation :servedBy, :businessProcesses, :BusinessProcess

data/lib/archsight/resources/technology_node.rb

@@ -36,7 +36,7 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
              enum: %w[vm bare-metal kubernetes-node network-appliance storage-array],
              summary: true
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :servedBy, :technologyServices, :TechnologyService
   relation :servedBy, :businessActors, :BusinessActor
 end

data/lib/archsight/resources/technology_service.rb

@@ -37,8 +37,8 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
 
   relation :suppliedBy, :technologyComponents, :TechnologySystemSoftware
   relation :servedBy, :businessActors, :BusinessActor
-  relation :realizes, :businessRequirements, :BusinessRequirement
-  relation :partiallyRealizes, :businessRequirements, :BusinessRequirement
-  relation :plans, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
   relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end