From b0f8d4e484686c65b0a531620ca1ad9e2ce7be06 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 14:15:12 +0100
Subject: [PATCH 01/11] docs: remove custom scripting in favor of native SBDL
 functionality

---
 .github/workflows/wc-document-generation.yml |  17 +-
 docs/support/gherkin-to-sbdl.py              |  39 -----
 docs/support/gherkin_mapping_config.py       | 106 -------------
 docs/support/gherkin_sbdl_converter.py       | 157 -------------------
 test/cpp/features/compatibility.feature      |  72 ++++++---
 5 files changed, 61 insertions(+), 330 deletions(-)
 delete mode 100755 docs/support/gherkin-to-sbdl.py
 delete mode 100644 docs/support/gherkin_mapping_config.py
 delete mode 100644 docs/support/gherkin_sbdl_converter.py

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index 581e94a2..fa682d6c 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -23,17 +23,22 @@ jobs:
         run: |
           set -Eeuo pipefail
           sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
-          python -m pip install gherkin-official==35.1.0 sbdl==1.16.4
+          python -m pip install gherkin-official==38.0.0 sbdl==1.21.3
+      - name: Build & Validate SBDL model
+        run: |
+          set -Eeuo pipefail
+          sbdl -m compile test/cpp/features/*.feature > ${RUNNER_TEMP}/amp-devcontainer.sbdl
       - name: Generate SRS document
         run: |
           set -Eeuo pipefail
-          python docs/support/gherkin-to-sbdl.py test/cpp/features/*.feature
-          sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 output.sbdl > software-requirements-specification.md
-      - uses: docker://pandoc/extra:3.7.0@sha256:a703d335fa237f8fc3303329d87e2555dca5187930da38bfa9010fa4e690933a
+          sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 ${RUNNER_TEMP}/amp-devcontainer.sbdl > software-requirements-specification.md
+      - uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
         with:
-          args: --template eisvogel --listings --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
+          args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
       - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: documents
-          path: "*.pdf"
+          path: |
+            ${RUNNER_TEMP}/amp-devcontainer.sbdl
+            "*.pdf"
           retention-days: 2
diff --git a/docs/support/gherkin-to-sbdl.py b/docs/support/gherkin-to-sbdl.py
deleted file mode 100755
index 8c6d505e..00000000
--- a/docs/support/gherkin-to-sbdl.py
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/usr/bin/env python3
-
-import argparse
-import os
-import sys
-
-from gherkin_mapping_config import FEATURE_RULE_CONFIG, FEATURE_RULE_SCENARIO_CONFIG
-from gherkin_sbdl_converter import GherkinConverter
-
-def main():
-    configs = {
-        'feature-rule': FEATURE_RULE_CONFIG,
-        'feature-rule-scenario': FEATURE_RULE_SCENARIO_CONFIG
-    }
-
-    parser = argparse.ArgumentParser(description='Configurable Gherkin to SBDL converter')
-    parser.add_argument('feature_files', nargs='+', help='Paths to feature files')
-    parser.add_argument('--output', '-o', default='output.sbdl', help='Output SBDL file')
-    parser.add_argument('--config', choices=configs.keys(), 
-                        default='feature-rule', help='Conversion configuration preset')
-
-    args = parser.parse_args()
-    config = configs[args.config]
-    converter = GherkinConverter(config)
-    gherkin_elements = []
-
-    for feature_path in args.feature_files:
-        if os.path.isfile(feature_path):
-            print(f"Processing {feature_path}")
-            elements = converter.extract_from_feature_file(feature_path)
-            gherkin_elements.extend(elements)
-        else:
-            print(f"File not found: {feature_path}", file=sys.stderr)
-
-    converter.write_sbdl_output(gherkin_elements, args.output)
-    print(f"Extracted {len(gherkin_elements)} elements to {args.output}")
-
-if __name__ == '__main__':
-    main()
diff --git a/docs/support/gherkin_mapping_config.py b/docs/support/gherkin_mapping_config.py
deleted file mode 100644
index 113e5e59..00000000
--- a/docs/support/gherkin_mapping_config.py
+++ /dev/null
@@ -1,106 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Configuration-driven Gherkin to SBDL mapping with flexible hierarchy support.
-"""
-
-from dataclasses import dataclass
-from typing import Dict, List, Optional, Union
-from enum import Enum
-
-class GherkinElementType(Enum):
-    """Supported Gherkin element types for conversion."""
-    FEATURE = "feature"
-    RULE = "rule"
-    SCENARIO = "scenario"
-    SCENARIO_OUTLINE = "scenario_outline"
-    EXAMPLE = "example"
-    BACKGROUND = "background"
-
-class SBDLElementType(Enum):
-    """Supported SBDL element types for mapping."""
-    REQUIREMENT = "requirement"
-    ASPECT = "aspect"
-    USECASE = "usecase"
-    DEFINITION = "definition"
-    TEST = "test"
-
-@dataclass
-class HierarchyMapping:
-    """Configuration for mapping Gherkin elements to SBDL with document hierarchy."""
-    gherkin_type: GherkinElementType
-    sbdl_type: SBDLElementType
-
-@dataclass
-class ConversionConfig:
-    """Complete configuration for Gherkin to SBDL conversion."""
-    hierarchy_mappings: List[HierarchyMapping]
-
-    def get_mapping_for_type(self, gherkin_type: GherkinElementType) -> Optional[HierarchyMapping]:
-        """Get the hierarchy mapping for a specific Gherkin element type."""
-        for mapping in self.hierarchy_mappings:
-            if mapping.gherkin_type == gherkin_type:
-                return mapping
-        return None
-
-# Predefined configurations for different use cases
-
-# Current Configuration (Feature -> Rule mapping)
-FEATURE_RULE_CONFIG = ConversionConfig(
-    hierarchy_mappings=[
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.FEATURE,
-            sbdl_type=SBDLElementType.REQUIREMENT
-        ),
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.RULE,
-            sbdl_type=SBDLElementType.REQUIREMENT
-        )
-    ]
-)
-
-# Extended Configuration (Feature -> Rule -> Scenario mapping)
-FEATURE_RULE_SCENARIO_CONFIG = ConversionConfig(
-    hierarchy_mappings=[
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.FEATURE,
-            sbdl_type=SBDLElementType.ASPECT
-        ),
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.RULE,
-            sbdl_type=SBDLElementType.REQUIREMENT
-        ),
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.SCENARIO,
-            sbdl_type=SBDLElementType.TEST
-        )
-    ]
-)
-
-# Flat Configuration (All as requirements at same level)
-FLAT_CONFIG = ConversionConfig(
-    hierarchy_mappings=[
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.FEATURE,
-            sbdl_type=SBDLElementType.REQUIREMENT
-        ),
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.RULE,
-            sbdl_type=SBDLElementType.REQUIREMENT
-        )
-    ]
-)
-
-# Use Case Focused Configuration
-USECASE_CONFIG = ConversionConfig(
-    hierarchy_mappings=[
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.FEATURE,
-            sbdl_type=SBDLElementType.USECASE
-        ),
-        HierarchyMapping(
-            gherkin_type=GherkinElementType.SCENARIO,
-            sbdl_type=SBDLElementType.USECASE
-        )
-    ]
-)
diff --git a/docs/support/gherkin_sbdl_converter.py b/docs/support/gherkin_sbdl_converter.py
deleted file mode 100644
index 888a8c6d..00000000
--- a/docs/support/gherkin_sbdl_converter.py
+++ /dev/null
@@ -1,157 +0,0 @@
-#!/usr/bin/env python3
-"""Gherkin to SBDL converter with configurable hierarchy mappings."""
-
-from dataclasses import dataclass
-from typing import List, Dict, Optional
-from textwrap import dedent
-import sys
-
-from gherkin.parser import Parser
-from gherkin.token_scanner import TokenScanner
-import sbdl
-
-from gherkin_mapping_config import (
-    ConversionConfig,
-    GherkinElementType,
-    SBDLElementType,
-)
-
-@dataclass
-class SBDLElement:
-    """A generalized SBDL element that can represent any type."""
-
-    identifier: str
-    element_type: SBDLElementType
-    description: str
-    parent: Optional[str] = None
-    metadata: Optional[Dict] = None
-
-    def __post_init__(self):
-        self.identifier = self._make_sbdl_identifier(self.identifier)
-        self.description = dedent(self.description)
-
-        if self.metadata is None:
-            self.metadata = {}
-
-    def _make_sbdl_identifier(self, name: str) -> str:
-        return sbdl.SBDL_Parser.sanitize_identifier(
-            name.replace(" ", "_").replace("-", "_")
-        ).strip("_")
-
-class GherkinConverter:
-    """Converts Gherkin files to SBDL using configurable hierarchy mappings."""
-
-    def __init__(self, config: ConversionConfig):
-        self.config = config
-        # Strategy map for element extraction: key in parsed Gherkin dict -> handler.
-        self._strategies = {
-            'feature': self._handle_feature,
-            'rule': self._handle_rule,
-            'scenario': self._handle_scenario,
-            'scenarioOutline': self._handle_scenario_outline,
-        }
-
-    def extract_from_feature_file(self, file_path: str) -> List[SBDLElement]:
-        """Extract all configured elements from a Gherkin feature file."""
-        try:
-            with open(file_path, 'r', encoding='utf-8') as file:
-                content = file.read()
-
-            parser = Parser()
-            feature_document = parser.parse(TokenScanner(content))
-
-            if 'feature' not in feature_document:
-                return []
-
-            return self._dispatch(feature_document, None)
-        except Exception as e:
-            print(f"Error parsing {file_path}: {e}", file=sys.stderr)
-            return []
-
-    def write_sbdl_output(self, elements: List[SBDLElement], output_file: str):
-        tokens = sbdl.SBDL_Parser.Tokens
-        attrs = sbdl.SBDL_Parser.Attributes
-
-        with open(output_file, 'w', encoding='utf-8') as f:
-            f.write("#!sbdl\n")
-
-            for element in elements:
-                escaped_desc = sbdl.SBDL_Parser.sanitize(element.description)
-                sbdl_type = element.element_type.value
-                f.write(f"{element.identifier} {tokens.declaration} {sbdl_type} ")
-                f.write(f"{tokens.declaration_group_delimeters[0]} ")
-                f.write(f"{attrs.description}{tokens.declaration_attribute_assign}")
-                f.write(
-                    f"{tokens.declaration_attribute_delimeter}{escaped_desc}{tokens.declaration_attribute_delimeter} "
-                )
-
-                if element.parent:
-                    f.write(f"{attrs.parent}{tokens.declaration_attribute_assign}{element.parent} ")
-
-                f.write(f"{tokens.declaration_group_delimeters[1]}\n")
-
-    def _extract_gherkin_element(self, element_data: Dict, element_type: GherkinElementType, parent_id: Optional[str]) -> Optional[SBDLElement]:
-        mapping = self.config.get_mapping_for_type(element_type)
-
-        if not mapping:
-            return None
-
-        name = element_data.get('name', '').strip()
-
-        if not name:
-            return None
-
-        return SBDLElement(
-            identifier=name,
-            element_type=mapping.sbdl_type,
-            description=element_data.get('description', ''),
-            parent=parent_id,
-            metadata={
-                'gherkin_type': element_type.value,
-                'original_name': name,
-                'line': element_data.get('location', {}).get('line'),
-            },
-        )
-
-    def _dispatch(self, node: Dict, parent_id: Optional[str]) -> List[SBDLElement]:
-        for key, handler in self._strategies.items():
-            if key in node:
-                return handler(node[key], parent_id)
-        return []
-
-    def _handle_feature(self, feature_data: Dict, parent_id: Optional[str]) -> List[SBDLElement]:
-        elements: List[SBDLElement] = []
-        feature_element = self._extract_gherkin_element(feature_data, GherkinElementType.FEATURE, parent_id)
-        feature_id = None
-        if feature_element:
-            elements.append(feature_element)
-            feature_id = feature_element.identifier
-            print(f"Extracted Feature: {feature_element.identifier}")
-        for child in feature_data.get('children', []):
-            elements.extend(self._dispatch(child, feature_id))
-        return elements
-
-    def _handle_rule(self, rule_data: Dict, parent_id: Optional[str]) -> List[SBDLElement]:
-        elements: List[SBDLElement] = []
-        rule_element = self._extract_gherkin_element(rule_data, GherkinElementType.RULE, parent_id)
-        if not rule_element:
-            return elements
-        elements.append(rule_element)
-        print(f"  Extracted Rule: {rule_element.identifier}")
-        for rule_child in rule_data.get('children', []):
-            elements.extend(self._dispatch(rule_child, rule_element.identifier))
-        return elements
-
-    def _handle_scenario(self, scenario_data: Dict, parent_id: Optional[str]) -> List[SBDLElement]:
-        scenario_element = self._extract_gherkin_element(scenario_data, GherkinElementType.SCENARIO, parent_id)
-        if not scenario_element:
-            return []
-        print(f"    Extracted Scenario: {scenario_element.identifier}")
-        return [scenario_element]
-
-    def _handle_scenario_outline(self, outline_data: Dict, parent_id: Optional[str]) -> List[SBDLElement]:
-        outline_element = self._extract_gherkin_element(outline_data, GherkinElementType.SCENARIO_OUTLINE, parent_id)
-        if not outline_element:
-            return []
-        print(f"    Extracted Scenario Outline: {outline_element.identifier}")
-        return [outline_element]
diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index 65cdebd8..c96e22e1 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -1,32 +1,60 @@
 Feature: Compatibility
 
-  As a software craftsperson,
-  to ensure that my development environment works well with a variety of tools and systems,
-  I want my development environment to be compatible with commonly used tools and systems.
+  @sbdl-begin
+    compatibility is aspect {
+      description is
+      "As a software craftsperson,
+       to ensure that my development environment works well with a variety of tools and systems,
+       I want my development environment to be compatible with commonly used tools and systems."
+    }
 
-  Rule: Open Container Initiative (OCI) Image Specification
-    amp-devcontainer images *SHALL* be compatible with the [OCI image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)
+    using { aspect is compatibility }
+  @sbdl-end
 
-    To guarantee compatibility with container runtimes and container- and image tooling; amp-devcontainer should be compatible with the OCI image specification.
+  Rule: Open Container Initiative (OCI) Image Specification
+    @sbdl-begin
+      req-compat-0001 is requirement {
+        custom:title is "@[-LINE]"
+        description is
+        "amp-devcontainer images *SHALL* be compatible with the [OCI image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)"
+        remark is
+        "To guarantee compatibility with container runtimes and container- and image tooling; amp-devcontainer should be compatible with the OCI image specification."
+      }
+    @sbdl-end
 
   Rule: Host architecture
-    amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64) host architectures.
-
-    Supporting both x86-64 and AArch64 has several advantages:
-
-    - Increasing useability on a wide range of host machines, from PC hardware using the x86-64 architecture to Apple Silicon using the AArch64 architecture
-    - Unlocking the power efficiency of the AArch64 architecture, potentially reducing energy consumption and cost for metered ci-systems
+    @sbdl-begin
+      req-compat-0002 is requirement {
+        custom:title is "@[-LINE]"
+        description is
+        "amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64) host architectures."
+        remark is
+        "Supporting both x86-64 and AArch64 has several advantages:\n\n- Increasing useability on a wide range of host machines, from PC hardware using the x86-64 architecture to Apple Silicon using the AArch64 architecture\n- Unlocking the power efficiency of the AArch64 architecture, potentially reducing energy consumption and cost for metered ci-systems"
+      }
+    @sbdl-end
 
   Rule: Integrated Development Environment (IDE)
-    amp-devcontainer *SHOULD* be compatible with [VS Code](https://code.visualstudio.com/) *and* [GitHub Codespaces](https://github.com/features/codespaces).
-
-    It should be possible to use amp-devcontainer and all of its features in both VS Code and GitHub Codespaces with minimal effort.
-    Where minimal effort means: with the least amount of additional set-up, user intervention or configuration for all functionality that is provided by amp-devcontainer.
-    Features and functions should work "out-of-the-box" without being overly opinionated.
+    @sbdl-begin
+      req-compat-0003 is requirement {
+        custom:title is "@[-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* be compatible with [VS Code](https://code.visualstudio.com/) *and* [GitHub Codespaces](https://github.com/features/codespaces)."
+        remark is
+        "It should be possible to use amp-devcontainer and all of its features in both VS Code and GitHub Codespaces with minimal effort.
+         Where minimal effort means: with the least amount of additional set-up, user intervention or configuration for all functionality that is provided by amp-devcontainer.
+         Features and functions should work \"out-of-the-box\" without being overly opinionated."
+      }
+    @sbdl-end
 
   Rule: GitHub Actions
-    amp-devcontainer *SHOULD* support seamless integration with [GitHub Actions](https://github.com/features/actions) without additional configuration.
-
-    Seamless integration with GitHub Actions allows users to easily incorporate amp-devcontainer into their ci/cd workflows.
-    This integration helps automate the build, test, and deployment processes, improving efficiency and reducing manual errors.
-    By minimizing the need for additional configuration, users can quickly set up and start using amp-devcontainer in their GitHub Actions workflows, enhancing their overall development experience.
+    @sbdl-begin
+      req-compat-0004 is requirement {
+        custom:title is "@[-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* support seamless integration with [GitHub Actions](https://github.com/features/actions) without additional configuration."
+        remark is
+        "Seamless integration with GitHub Actions allows users to easily incorporate amp-devcontainer into their ci/cd workflows.
+         This integration helps automate the build, test, and deployment processes, improving efficiency and reducing manual errors.
+         By minimizing the need for additional configuration, users can quickly set up and start using amp-devcontainer in their GitHub Actions workflows, enhancing their overall development experience."
+      }
+    @sbdl-end

From 78a81a0dc459f1f0cc657d52c55e650152094ed6 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 14:32:57 +0100
Subject: [PATCH 02/11] docs: Update SRS template

---
 .../software-requirements-specification.md.j2 | 22 +++++++++----------
 test/cpp/features/compatibility.feature       |  8 +++----
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/docs/templates/software-requirements-specification.md.j2 b/docs/templates/software-requirements-specification.md.j2
index dda4cbeb..35edb225 100644
--- a/docs/templates/software-requirements-specification.md.j2
+++ b/docs/templates/software-requirements-specification.md.j2
@@ -46,24 +46,24 @@ The containers may be used both for local development and continuous integration
 {{ text.encode('utf-8').decode('unicode_escape') }}
 {%- endmacro -%}
 
-{%- macro sbdl_id_to_header(text) -%}
-{{ text.replace('_', ' ') }}
+{%- macro strip_rule_prefix(text) -%}
+{{ text | replace('Rule: ', '') }}
 {%- endmacro -%}
 
-{%- for req_id, requirement in sbdl.items() %}
-{%- if requirement.type == 'requirement' and 'parent' not in requirement %}
+{%- for aspect_id, aspect in sbdl.items() %}
+{%- if aspect.type == 'aspect' %}
 
-## {{ reencode(sbdl_id_to_header(req_id)) }}
+## {{ reencode(strip_rule_prefix(aspect_id)) | title }}
 
-{{ reencode(requirement.description) }}
+{{ reencode(aspect.description) }}
 
-{%- if 'child' in requirement %}
-{%- for child in requirement.child %}
-{%- set child_req = sbdl[child.identifier] %}
+{%- if 'requirement' in aspect %}
+{%- for req_ref in aspect.requirement %}
+{%- set req = sbdl[req_ref.identifier] %}
 
-### {{ reencode(sbdl_id_to_header(child.identifier)) }}
+### {{ req_ref.identifier }}: {{ reencode(strip_rule_prefix(req['custom:title'])) }}
 
-{{ reencode(child_req.description) }}
+{{ reencode(req.description) }}
 
 {%- endfor %}
 {%- endif %}
diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index c96e22e1..a9b66b68 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -14,7 +14,7 @@ Feature: Compatibility
   Rule: Open Container Initiative (OCI) Image Specification
     @sbdl-begin
       req-compat-0001 is requirement {
-        custom:title is "@[-LINE]"
+        custom:title is "[@-LINE]"
         description is
         "amp-devcontainer images *SHALL* be compatible with the [OCI image specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)"
         remark is
@@ -25,7 +25,7 @@ Feature: Compatibility
   Rule: Host architecture
     @sbdl-begin
       req-compat-0002 is requirement {
-        custom:title is "@[-LINE]"
+        custom:title is "[@-LINE]"
         description is
         "amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64) host architectures."
         remark is
@@ -36,7 +36,7 @@ Feature: Compatibility
   Rule: Integrated Development Environment (IDE)
     @sbdl-begin
       req-compat-0003 is requirement {
-        custom:title is "@[-LINE]"
+        custom:title is "[@-LINE]"
         description is
         "amp-devcontainer *SHOULD* be compatible with [VS Code](https://code.visualstudio.com/) *and* [GitHub Codespaces](https://github.com/features/codespaces)."
         remark is
@@ -49,7 +49,7 @@ Feature: Compatibility
   Rule: GitHub Actions
     @sbdl-begin
       req-compat-0004 is requirement {
-        custom:title is "@[-LINE]"
+        custom:title is "[@-LINE]"
         description is
         "amp-devcontainer *SHOULD* support seamless integration with [GitHub Actions](https://github.com/features/actions) without additional configuration."
         remark is

From 6d1a337b61447efe81c153e878fbef454401e149 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 14:41:08 +0100
Subject: [PATCH 03/11] docs: fix artifact paths

---
 .github/workflows/wc-document-generation.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index fa682d6c..27b02b49 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -39,6 +39,6 @@ jobs:
         with:
           name: documents
           path: |
-            ${RUNNER_TEMP}/amp-devcontainer.sbdl
-            "*.pdf"
+            ${{ env.RUNNER_TEMP }}/amp-devcontainer.sbdl
+            *.pdf
           retention-days: 2

From 8e40e072fed1fa2ed814d00ec3dd24c6c97c8cc2 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 14:47:07 +0100
Subject: [PATCH 04/11] docs: change paths

---
 .github/workflows/wc-document-generation.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index 27b02b49..cf7e0779 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -27,11 +27,11 @@ jobs:
       - name: Build & Validate SBDL model
         run: |
           set -Eeuo pipefail
-          sbdl -m compile test/cpp/features/*.feature > ${RUNNER_TEMP}/amp-devcontainer.sbdl
+          sbdl -m compile test/cpp/features/*.feature > amp-devcontainer.sbdl
       - name: Generate SRS document
         run: |
           set -Eeuo pipefail
-          sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 ${RUNNER_TEMP}/amp-devcontainer.sbdl > software-requirements-specification.md
+          sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 amp-devcontainer.sbdl > software-requirements-specification.md
       - uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
         with:
           args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
@@ -39,6 +39,6 @@ jobs:
         with:
           name: documents
           path: |
-            ${{ env.RUNNER_TEMP }}/amp-devcontainer.sbdl
             *.pdf
+            *.sbdl
           retention-days: 2

From 1502243b39e47cdb72215c28a4dc8baf7bec030f Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 15:18:45 +0100
Subject: [PATCH 05/11] docs: homogonize titles

---
 .../software-requirements-specification.md.j2        | 12 +++++++-----
 test/cpp/features/compatibility.feature              |  2 +-
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/templates/software-requirements-specification.md.j2 b/docs/templates/software-requirements-specification.md.j2
index 35edb225..d07ceb54 100644
--- a/docs/templates/software-requirements-specification.md.j2
+++ b/docs/templates/software-requirements-specification.md.j2
@@ -2,7 +2,7 @@
 title: "Software requirements specification for amp-devcontainer"
 author: ["@rjaegers"]
 colorlinks: true
-date: "October-2025"
+date: "February-2026"
 keywords: [Software, Requirements, SRS, amp-devcontainer]
 lang: "en"
 titlepage: true
@@ -46,14 +46,14 @@ The containers may be used both for local development and continuous integration
 {{ text.encode('utf-8').decode('unicode_escape') }}
 {%- endmacro -%}
 
-{%- macro strip_rule_prefix(text) -%}
-{{ text | replace('Rule: ', '') }}
+{%- macro strip_gherkin_prefix(text) -%}
+{{ text | replace('Rule: ', '') | replace('Feature: ', '') }}
 {%- endmacro -%}
 
 {%- for aspect_id, aspect in sbdl.items() %}
 {%- if aspect.type == 'aspect' %}
 
-## {{ reencode(strip_rule_prefix(aspect_id)) | title }}
+## {{ reencode(strip_gherkin_prefix(aspect_id)) | title }}
 
 {{ reencode(aspect.description) }}
 
@@ -61,10 +61,12 @@ The containers may be used both for local development and continuous integration
 {%- for req_ref in aspect.requirement %}
 {%- set req = sbdl[req_ref.identifier] %}
 
-### {{ req_ref.identifier }}: {{ reencode(strip_rule_prefix(req['custom:title'])) }}
+### {{ req_ref.identifier }}: {{ reencode(strip_gherkin_prefix(req['custom:title'])) }}
 
 {{ reencode(req.description) }}
 
+{{ reencode(req.remark) }}
+
 {%- endfor %}
 {%- endif %}
 {%- endif %}
diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index a9b66b68..3703dfd0 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -1,7 +1,7 @@
 Feature: Compatibility
-
   @sbdl-begin
     compatibility is aspect {
+      custom:title is "[@-LINE]"
       description is
       "As a software craftsperson,
        to ensure that my development environment works well with a variety of tools and systems,

From 894c137de73e03c00ad21785ec76bcaba7b8a1e1 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 16:37:33 +0100
Subject: [PATCH 06/11] docs: try to create a valid Gherkin SBDL hybrid

---
 test/cpp/features/compatibility.feature | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index 3703dfd0..1e3530ff 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -1,5 +1,7 @@
 Feature: Compatibility
+
   @sbdl-begin
+    """
     compatibility is aspect {
       custom:title is "[@-LINE]"
       description is
@@ -10,8 +12,10 @@ Feature: Compatibility
 
     using { aspect is compatibility }
   @sbdl-end
+  """
 
   Rule: Open Container Initiative (OCI) Image Specification
+
     @sbdl-begin
       req-compat-0001 is requirement {
         custom:title is "[@-LINE]"
@@ -23,6 +27,7 @@ Feature: Compatibility
     @sbdl-end
 
   Rule: Host architecture
+
     @sbdl-begin
       req-compat-0002 is requirement {
         custom:title is "[@-LINE]"
@@ -34,6 +39,7 @@ Feature: Compatibility
     @sbdl-end
 
   Rule: Integrated Development Environment (IDE)
+
     @sbdl-begin
       req-compat-0003 is requirement {
         custom:title is "[@-LINE]"
@@ -47,6 +53,7 @@ Feature: Compatibility
     @sbdl-end
 
   Rule: GitHub Actions
+
     @sbdl-begin
       req-compat-0004 is requirement {
         custom:title is "[@-LINE]"

From 18c31e7fad1cf0e879e58619c29d50bb9ae3ec5c Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 16:41:12 +0100
Subject: [PATCH 07/11] docs: remove leftover from previous experiment

---
 test/cpp/features/compatibility.feature | 2 --
 1 file changed, 2 deletions(-)

diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index 1e3530ff..1b66112f 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -1,7 +1,6 @@
 Feature: Compatibility
 
   @sbdl-begin
-    """
     compatibility is aspect {
       custom:title is "[@-LINE]"
       description is
@@ -12,7 +11,6 @@ Feature: Compatibility
 
     using { aspect is compatibility }
   @sbdl-end
-  """
 
   Rule: Open Container Initiative (OCI) Image Specification
 

From 29f74faf97c9df2092fd64e3219662445367faab Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Sat, 28 Feb 2026 16:53:39 +0100
Subject: [PATCH 08/11] docs: unconfuse Gherkin parser by commenting
 @sbdl-[begin|end]

The @sbdl markers were seen as tags
---
 test/cpp/features/compatibility.feature | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index 1b66112f..5d9012c9 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -1,6 +1,5 @@
 Feature: Compatibility
-
-  @sbdl-begin
+  # @sbdl-begin
     compatibility is aspect {
       custom:title is "[@-LINE]"
       description is
@@ -10,11 +9,10 @@ Feature: Compatibility
     }
 
     using { aspect is compatibility }
-  @sbdl-end
+  # @sbdl-end
 
   Rule: Open Container Initiative (OCI) Image Specification
-
-    @sbdl-begin
+    # @sbdl-begin
       req-compat-0001 is requirement {
         custom:title is "[@-LINE]"
         description is
@@ -22,11 +20,10 @@ Feature: Compatibility
         remark is
         "To guarantee compatibility with container runtimes and container- and image tooling; amp-devcontainer should be compatible with the OCI image specification."
       }
-    @sbdl-end
+    # @sbdl-end
 
   Rule: Host architecture
-
-    @sbdl-begin
+    # @sbdl-begin
       req-compat-0002 is requirement {
         custom:title is "[@-LINE]"
         description is
@@ -34,11 +31,10 @@ Feature: Compatibility
         remark is
         "Supporting both x86-64 and AArch64 has several advantages:\n\n- Increasing useability on a wide range of host machines, from PC hardware using the x86-64 architecture to Apple Silicon using the AArch64 architecture\n- Unlocking the power efficiency of the AArch64 architecture, potentially reducing energy consumption and cost for metered ci-systems"
       }
-    @sbdl-end
+    # @sbdl-end
 
   Rule: Integrated Development Environment (IDE)
-
-    @sbdl-begin
+    # @sbdl-begin
       req-compat-0003 is requirement {
         custom:title is "[@-LINE]"
         description is
@@ -48,11 +44,10 @@ Feature: Compatibility
          Where minimal effort means: with the least amount of additional set-up, user intervention or configuration for all functionality that is provided by amp-devcontainer.
          Features and functions should work \"out-of-the-box\" without being overly opinionated."
       }
-    @sbdl-end
+    # @sbdl-end
 
   Rule: GitHub Actions
-
-    @sbdl-begin
+    # @sbdl-begin
       req-compat-0004 is requirement {
         custom:title is "[@-LINE]"
         description is
@@ -62,4 +57,4 @@ Feature: Compatibility
          This integration helps automate the build, test, and deployment processes, improving efficiency and reducing manual errors.
          By minimizing the need for additional configuration, users can quickly set up and start using amp-devcontainer in their GitHub Actions workflows, enhancing their overall development experience."
       }
-    @sbdl-end
+    # @sbdl-end

From 899146be495ac68bbf759d4dd264173572fed105 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Mon, 2 Mar 2026 13:56:29 +0000
Subject: [PATCH 09/11] docs: update all scenarios

---
 test/cpp/features/compatibility.feature       |  2 +-
 test/cpp/features/compilation.feature         | 77 +++++++++------
 test/cpp/features/debugging.feature           | 49 +++++++---
 test/cpp/features/maintainability.feature     | 91 ++++++++++++------
 test/cpp/features/security.feature            | 61 ++++++++----
 .../features/static-dynamic-analysis.feature  | 93 +++++++++++++------
 6 files changed, 256 insertions(+), 117 deletions(-)

diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
index 5d9012c9..bd9558ae 100644
--- a/test/cpp/features/compatibility.feature
+++ b/test/cpp/features/compatibility.feature
@@ -29,7 +29,7 @@ Feature: Compatibility
         description is
         "amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64) host architectures."
         remark is
-        "Supporting both x86-64 and AArch64 has several advantages:\n\n- Increasing useability on a wide range of host machines, from PC hardware using the x86-64 architecture to Apple Silicon using the AArch64 architecture\n- Unlocking the power efficiency of the AArch64 architecture, potentially reducing energy consumption and cost for metered ci-systems"
+        "Supporting both x86-64 and AArch64 has several advantages:\n\n- Increasing usability on a wide range of host machines, from PC hardware using the x86-64 architecture to Apple Silicon using the AArch64 architecture\n- Unlocking the power efficiency of the AArch64 architecture, potentially reducing energy consumption and cost for metered ci-systems"
       }
     # @sbdl-end
 
diff --git a/test/cpp/features/compilation.feature b/test/cpp/features/compilation.feature
index de0e3e3c..fae76776 100644
--- a/test/cpp/features/compilation.feature
+++ b/test/cpp/features/compilation.feature
@@ -1,18 +1,27 @@
 Feature: Compilation
+  # @sbdl-begin
+    compilation is aspect {
+      custom:title is "[@-LINE]"
+      description is
+      "As a software developer,
+       to generate a working product, when using compiled languages,
+       source code needs to be compiled into working software."
+    }
 
-  As a software developer,
-  to generate a working product, when using compiled languages,
-  source code needs to be compiled into working software.
+    using { aspect is compilation }
+  # @sbdl-end
 
   Rule: Compile for container host architecture and operating system
-    amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture and operating system.
-
-    Compiling valid source code into working software, able to run on the container host architecture and operating system,
-    can be necessary in several scenarios; for example when:
-
-    - the container host is the deployment target
-    - running tests on the container host
-    - building plug-ins, extensions, code generators, or other additional tools that need to run on the container host
+    # @sbdl-begin
+      req-comp-0001 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture and operating system."
+        remark is
+        "Compiling valid source code into working software, able to run on the container host architecture and operating system,
+         can be necessary in several scenarios; for example when:\n\n- the container host is the deployment target\n- running tests on the container host\n- building plug-ins, extensions, code generators, or other additional tools that need to run on the container host"
+      }
+    # @sbdl-end
 
     @flavor:cpp
     Scenario: Compile valid source code into working software targeting the container host architecture
@@ -22,24 +31,36 @@ Feature: Compilation
       Then the output should contain "Build finished with exit code 0"
 
   Rule: Compile for ARM Cortex target architecture
-    amp-devcontainer *SHOULD* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture.
-
-    Compiling valid source-code into working ELF executables, able to run on the ARM Cortex architecture,
-    is a primary function for amp-devcontainer. It enables building firmware for micro-controllers based
-    on the ARM Cortex architecture.
+    # @sbdl-begin
+      req-comp-0002 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture."
+        remark is
+        "Compiling valid source-code into working ELF executables, able to run on the ARM Cortex architecture,
+         is a primary function for amp-devcontainer. It enables building firmware for micro-controllers based
+         on the ARM Cortex architecture."
+      }
+    # @sbdl-end
 
   Rule: Compile for Microsoft® Windows operating system
-    amp-devcontainer *SHOULD* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system.
-
-    Compiling valid source-code into working executables, able to run on the Microsoft® Windows operating system, can be necessary in several scenarios e.g.
-
-    - Cross platform code is written and needs to be compiled and deployed
-    - Executables needs to be deployed outside of container context to a host running the Microsoft® Windows operating system
+    # @sbdl-begin
+      req-comp-0003 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system."
+        remark is
+        "Compiling valid source-code into working executables, able to run on the Microsoft® Windows operating system, can be necessary in several scenarios e.g.\n\n- Cross platform code is written and needs to be compiled and deployed\n- Executables needs to be deployed outside of container context to a host running the Microsoft® Windows operating system"
+      }
+    # @sbdl-end
 
   Rule: Compilation cache
-    amp-devcontainer *MAY* be able to cache the results of a compilation to speed-up subsequent compilations.
-
-    Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like:
-
-    - Reduce developer waiting time and context switches, [maintaining flow-state](https://azure.microsoft.com/en-us/blog/quantifying-the-impact-of-developer-experience/)
-    - Reduce CPU usage at the cost of more storage usage, potentially reducing energy consumption and cost for metered ci-systems
+    # @sbdl-begin
+      req-comp-0004 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *MAY* be able to cache the results of a compilation to speed-up subsequent compilations."
+        remark is
+        "Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like:\n\n- Reduce developer waiting time and context switches, [maintaining flow-state](https://azure.microsoft.com/en-us/blog/quantifying-the-impact-of-developer-experience/)\n- Reduce CPU usage at the cost of more storage usage, potentially reducing energy consumption and cost for metered ci-systems"
+      }
+    # @sbdl-end
diff --git a/test/cpp/features/debugging.feature b/test/cpp/features/debugging.feature
index 58a64287..8e5b66a1 100644
--- a/test/cpp/features/debugging.feature
+++ b/test/cpp/features/debugging.feature
@@ -1,21 +1,40 @@
 Feature: Debugging
+  # @sbdl-begin
+    debugging is aspect {
+      custom:title is "[@-LINE]"
+      description is
+      "As a software craftsperson,
+       to efficiently identify and resolve issues in my code,
+       I want to be able to debug my source code within the development environment."
+    }
 
-  As a software craftsperson,
-  to efficiently identify and resolve issues in my code,
-  I want to be able to debug my source code within the development environment.
+    using { aspect is debugging }
+  # @sbdl-end
 
   Rule: Debugging support
-    amp-devcontainer *SHALL* provide debugging support for the primary programming language(s) used within the container.
-
-    Providing debugging support within the development environment enhances the developer experience and productivity.
-    It allows developers to efficiently identify and resolve issues in their code by setting breakpoints, inspecting variables, and stepping through code execution.
-    This capability is essential for diagnosing complex problems, understanding code flow, and ensuring the correctness of software.
-    By having integrated debugging tools, developers can streamline their workflow and reduce the time spent on troubleshooting and fixing bugs.
+    # @sbdl-begin
+      req-debug-0001 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHALL* provide debugging support for the primary programming language(s) used within the container."
+        remark is
+        "Providing debugging support within the development environment enhances the developer experience and productivity.
+         It allows developers to efficiently identify and resolve issues in their code by setting breakpoints, inspecting variables, and stepping through code execution.
+         This capability is essential for diagnosing complex problems, understanding code flow, and ensuring the correctness of software.
+         By having integrated debugging tools, developers can streamline their workflow and reduce the time spent on troubleshooting and fixing bugs."
+      }
+    # @sbdl-end
 
   Rule: Upload firmware to micro-controller
-    amp-devcontainer *MAY* provide tools to upload compiled firmware to a connected micro-controller.
-
-    Providing tools to upload compiled firmware to a connected micro-controller enhances the development workflow for embedded systems.
-    It allows developers to quickly and easily transfer their compiled code to the target hardware for testing and debugging.
-    This capability is essential for validating the functionality of the firmware on the actual device, ensuring that it behaves as expected in real-world scenarios.
-    By having integrated tools for firmware upload, developers can streamline their workflow, reduce manual steps, and improve overall productivity when working with micro-controllers.
+    # @sbdl-begin
+      req-debug-0002 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *MAY* provide tools to upload compiled firmware to a connected micro-controller."
+        remark is
+        "Providing tools to upload compiled firmware to a connected micro-controller enhances the development workflow for embedded systems.
+         It allows developers to quickly and easily transfer their compiled code to the target hardware for testing and debugging.
+         This capability is essential for validating the functionality of the firmware on the actual device, ensuring that it behaves as expected in real-world scenarios.
+         By having integrated tools for firmware upload, developers can streamline their workflow, reduce manual steps, and improve overall productivity when working with micro-controllers."
+      }
+    # @sbdl-end
diff --git a/test/cpp/features/maintainability.feature b/test/cpp/features/maintainability.feature
index aa384582..516e136c 100644
--- a/test/cpp/features/maintainability.feature
+++ b/test/cpp/features/maintainability.feature
@@ -1,42 +1,79 @@
 Feature: Maintainability
+  # @sbdl-begin
+    maintainability is aspect {
+      custom:title is "[@-LINE]"
+      description is
+      "As a software craftsperson,
+       to ensure that I have access to a stable and reliable development environment,
+       I want my development environment to be maintainable over time."
+    }
 
-  As a software craftsperson,
-  to ensure that I have access to a stable and reliable development environment,
-  I want my development environment to be maintainable over time.
+    using { aspect is maintainability }
+  # @sbdl-end
 
   Rule: Tool and dependency updates
-    amp-devcontainer *SHOULD* contain up-to-date tools and dependencies.
-
-    Keeping tools and dependencies up-to-date helps ensure that the development environment remains secure, stable, and compatible with the latest technologies.
-    It also helps prevent issues related to deprecated or unsupported software versions, reducing maintenance overhead and improving overall developer productivity.
-    Regular updates can also introduce new features and improvements that enhance the development experience.
+    # @sbdl-begin
+      req-maint-0001 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* contain up-to-date tools and dependencies."
+        remark is
+        "Keeping tools and dependencies up-to-date helps ensure that the development environment remains secure, stable, and compatible with the latest technologies.
+         It also helps prevent issues related to deprecated or unsupported software versions, reducing maintenance overhead and improving overall developer productivity.
+         Regular updates can also introduce new features and improvements that enhance the development experience."
+      }
+    # @sbdl-end
 
   Rule: Automatic updates
-    amp-devcontainer *SHOULD* provide support for automatic updates when consumed as a dependency.
-
-    Providing support for automatic updates when amp-devcontainer is consumed as a dependency helps ensure that users always have access to the latest features, bug fixes, and security patches.
-    This reduces the maintenance burden on users, as they do not need to manually track and apply updates.
-    Automatic updates can also help ensure compatibility with other dependencies and tools, improving the overall stability and reliability of the development environment.
+    # @sbdl-begin
+      req-maint-0002 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* provide support for automatic updates when consumed as a dependency."
+        remark is
+        "Providing support for automatic updates when amp-devcontainer is consumed as a dependency helps ensure that users always have access to the latest features, bug fixes, and security patches.
+         This reduces the maintenance burden on users, as they do not need to manually track and apply updates.
+         Automatic updates can also help ensure compatibility with other dependencies and tools, improving the overall stability and reliability of the development environment."
+      }
+    # @sbdl-end
 
   Rule: Re-usable build system
-    amp-devcontainer *SHOULD* provide re-usable building blocks to enable building, publishing and testing derived containers.
-
-    Providing re-usable building blocks for building, publishing and testing derived containers reduces duplication, and ensures consistent application of practices.
-    Derived containers (i.e. containers using amp-devcontainer as a base for further extension) should be able to build, push and test in the same way that amp-devcontainer does, without the need to duplicate the build system.
+    # @sbdl-begin
+      req-maint-0003 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* provide re-usable building blocks to enable building, publishing and testing derived containers."
+        remark is
+        "Providing re-usable building blocks for building, publishing and testing derived containers reduces duplication, and ensures consistent application of practices.
+         Derived containers (i.e. containers using amp-devcontainer as a base for further extension) should be able to build, push and test in the same way that amp-devcontainer does, without the need to duplicate the build system."
+      }
+    # @sbdl-end
 
   Rule: Architectural decisions
-    amp-devcontainer *SHOULD* document its architectural decisions.
-
-    Documenting architectural decisions helps provide context and rationale for the design choices made in the development environment.
-    This information can be valuable for future maintainers, as it helps them understand the reasoning behind certain implementations and can guide them in making informed decisions when modifying or extending the environment.
-    Clear documentation of architectural decisions can also facilitate collaboration among team members and improve overall maintainability.
+    # @sbdl-begin
+      req-maint-0004 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* document its architectural decisions."
+        remark is
+        "Documenting architectural decisions helps provide context and rationale for the design choices made in the development environment.
+         This information can be valuable for future maintainers, as it helps them understand the reasoning behind certain implementations and can guide them in making informed decisions when modifying or extending the environment.
+         Clear documentation of architectural decisions can also facilitate collaboration among team members and improve overall maintainability."
+      }
+    # @sbdl-end
 
   Rule: Container image size
-    amp-devcontainer *SHOULD* aim to keep its container image size as small as possible without compromising functionality.
-
-    Keeping the container image size small helps improve performance, reduce resource consumption, and minimize the time required to download and deploy the development environment.
-    A smaller image size can also help reduce storage costs and improve scalability, particularly in cloud-based environments.
-    By optimizing the container image size, amp-devcontainer can provide a more efficient and user-friendly experience for developers.
+    # @sbdl-begin
+      req-maint-0005 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* aim to keep its container image size as small as possible without compromising functionality."
+        remark is
+        "Keeping the container image size small helps improve performance, reduce resource consumption, and minimize the time required to download and deploy the development environment.
+         A smaller image size can also help reduce storage costs and improve scalability, particularly in cloud-based environments.
+         By optimizing the container image size, amp-devcontainer can provide a more efficient and user-friendly experience for developers."
+      }
+    # @sbdl-end
 
     <acceptance-criteria>
     - The container image size is monitored.
diff --git a/test/cpp/features/security.feature b/test/cpp/features/security.feature
index 061a0053..eff653e2 100644
--- a/test/cpp/features/security.feature
+++ b/test/cpp/features/security.feature
@@ -1,26 +1,51 @@
 Feature: Security
+  # @sbdl-begin
+    security is aspect {
+      custom:title is "[@-LINE]"
+      description is
+      "As a security engineer and security conscious developer,
+       to have control over the security posture of my development environment,
+       I want to have controls in place to identify and mitigate supply-chain vulnerabilities."
+    }
 
-  As a security engineer and security conscious developer,
-  to have control over the security posture of my development environment,
-  I want to have controls in place to identify and mitigate supply-chain vulnerabilities.
+    using { aspect is security }
+  # @sbdl-end
 
   Rule: Build provenance
-    amp-devcontainer *SHALL* include build provenance as specified in [SLSA v1.0 Build L3](https://slsa.dev/spec/v1.0/levels).
-
-    Including provenance gives confidence that the container images haven't been tampered with and can be securely traced back to its source code.
-    The primary purpose is to enable [verification](https://slsa.dev/spec/v1.0/verifying-artifacts) that the container image was built as expected.
-    Consumers have some way of knowing what the expected provenance should look like for a given container image and then compare each container image's actual provenance to those expectations.
-    Doing so prevents several classes of [supply chain threats](https://slsa.dev/spec/v1.0/threats).
+    # @sbdl-begin
+      req-sec-0001 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHALL* include build provenance as specified in [SLSA v1.0 Build L3](https://slsa.dev/spec/v1.0/levels)."
+        remark is
+        "Including provenance gives confidence that the container images haven't been tampered with and can be securely traced back to its source code.
+         The primary purpose is to enable [verification](https://slsa.dev/spec/v1.0/verifying-artifacts) that the container image was built as expected.
+         Consumers have some way of knowing what the expected provenance should look like for a given container image and then compare each container image's actual provenance to those expectations.
+         Doing so prevents several classes of [supply chain threats](https://slsa.dev/spec/v1.0/threats)."
+      }
+    # @sbdl-end
 
   Rule: Signing
-    amp-devcontainer *SHALL* cryptographically sign its released container images.
-
-    Cryptographically signing released container images provides integrity and authenticity guarantees.
-    It enables consumers to verify that the container image hasn't been tampered with and that it indeed originates from the expected publisher.
-    This helps mitigate several classes of [supply chain threats](https://slsa.dev/spec/v1.0/threats).
+    # @sbdl-begin
+      req-sec-0002 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHALL* cryptographically sign its released container images."
+        remark is
+        "Cryptographically signing released container images provides integrity and authenticity guarantees.
+         It enables consumers to verify that the container image hasn't been tampered with and that it indeed originates from the expected publisher.
+         This helps mitigate several classes of [supply chain threats](https://slsa.dev/spec/v1.0/threats)."
+      }
+    # @sbdl-end
 
   Rule: Software Bill of Materials (SBOM)
-    amp-devcontainer *SHOULD* provide a Software Bill of Materials (SBOM) for its released container images.
-
-    Providing a Software Bill of Materials (SBOM) enables consumers to identify and manage security risks associated with the software components included in the container images.
-    It helps identify known vulnerabilities, license compliance issues, and potential supply chain risks.
+    # @sbdl-begin
+      req-sec-0003 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* provide a Software Bill of Materials (SBOM) for its released container images."
+        remark is
+        "Providing a Software Bill of Materials (SBOM) enables consumers to identify and manage security risks associated with the software components included in the container images.
+         It helps identify known vulnerabilities, license compliance issues, and potential supply chain risks."
+      }
+    # @sbdl-end
diff --git a/test/cpp/features/static-dynamic-analysis.feature b/test/cpp/features/static-dynamic-analysis.feature
index 3254790a..e794ef3a 100644
--- a/test/cpp/features/static-dynamic-analysis.feature
+++ b/test/cpp/features/static-dynamic-analysis.feature
@@ -1,15 +1,28 @@
 Feature: Static and dynamic analysis
+  # @sbdl-begin
+    static-and-dynamic-analysis is aspect {
+      custom:title is "[@-LINE]"
+      description is
+      "As a software craftsperson,
+       to maintain consistent, high-quality and bug-free code,
+       I want my source code to be statically and dynamically analyzed."
+    }
 
-  As a software craftsperson,
-  to maintain consistent, high-quality and bug-free code,
-  I want my source code to be statically and dynamically analyzed.
+    using { aspect is static-and-dynamic-analysis }
+  # @sbdl-end
 
   Rule: Code formatting
-    amp-devcontainer *MAY* provide code formatting tools for the primary programming language(s) used within the container.
-
-    Providing code formatting tools helps maintain a consistent coding style across the codebase, improving readability and reducing friction during code reviews.
-    It also helps catch potential issues early by enforcing coding standards and best practices.
-    By integrating code formatting tools into the development environment, developers can easily format their code according to predefined rules, ensuring that the code adheres to the project's style guidelines.
+    # @sbdl-begin
+      req-sda-0001 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *MAY* provide code formatting tools for the primary programming language(s) used within the container."
+        remark is
+        "Providing code formatting tools helps maintain a consistent coding style across the codebase, improving readability and reducing friction during code reviews.
+         It also helps catch potential issues early by enforcing coding standards and best practices.
+         By integrating code formatting tools into the development environment, developers can easily format their code according to predefined rules, ensuring that the code adheres to the project's style guidelines."
+      }
+    # @sbdl-end
 
   @flavor:cpp @fixme
   Scenario: Format source code according to a formatting style
@@ -19,29 +32,53 @@ Feature: Static and dynamic analysis
     Then the contents of "clang-tools/unformatted.cpp" should match the contents of "clang-tools/formatted.cpp"
 
   Rule: Static analysis
-    amp-devcontainer *MAY* provide static analysis tools for the primary programming language(s) used within the container.
-
-    Providing static analysis tools helps identify potential issues in the code before it is executed, improving code quality and reducing the likelihood of runtime errors.
-    These tools can analyze the code for common pitfalls, coding standards violations, and potential bugs, providing developers with valuable feedback early in the development process.
-    By integrating static analysis tools into the development environment, developers can catch issues before they become more significant problems, streamlining the development workflow and improving overall code quality.
+    # @sbdl-begin
+      req-sda-0002 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *MAY* provide static analysis tools for the primary programming language(s) used within the container."
+        remark is
+        "Providing static analysis tools helps identify potential issues in the code before it is executed, improving code quality and reducing the likelihood of runtime errors.
+         These tools can analyze the code for common pitfalls, coding standards violations, and potential bugs, providing developers with valuable feedback early in the development process.
+         By integrating static analysis tools into the development environment, developers can catch issues before they become more significant problems, streamlining the development workflow and improving overall code quality."
+      }
+    # @sbdl-end
 
   Rule: Coverage analysis
-    amp-devcontainer *SHOULD* provide code coverage analysis tools for the primary programming language(s) used within the container.
-
-    Providing code coverage analysis tools helps assess the effectiveness of the existing test suite by measuring how much of the code is exercised by the tests.
-    This information can help identify gaps in test coverage, ensuring that critical parts of the code are adequately tested.
-    By integrating code coverage analysis tools into the development environment, developers can improve their test suites, leading to higher code quality and increased confidence in the software's correctness.
+    # @sbdl-begin
+      req-sda-0003 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *SHOULD* provide code coverage analysis tools for the primary programming language(s) used within the container."
+        remark is
+        "Providing code coverage analysis tools helps assess the effectiveness of the existing test suite by measuring how much of the code is exercised by the tests.
+         This information can help identify gaps in test coverage, ensuring that critical parts of the code are adequately tested.
+         By integrating code coverage analysis tools into the development environment, developers can improve their test suites, leading to higher code quality and increased confidence in the software's correctness."
+      }
+    # @sbdl-end
 
   Rule: Mutation testing
-    amp-devcontainer *MAY* provide mutation testing tools for the primary programming language(s) used within the container.
-
-    Providing mutation testing tools helps assess the effectiveness of the existing test suite by introducing small changes (mutations) to the code and checking if the tests can detect these changes.
-    This process helps identify gaps in test coverage and ensures that the tests are robust enough to catch potential issues in the code.
-    By integrating mutation testing tools into the development environment, developers can improve their test suites, leading to higher code quality and increased confidence in the software's correctness.
+    # @sbdl-begin
+      req-sda-0004 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *MAY* provide mutation testing tools for the primary programming language(s) used within the container."
+        remark is
+        "Providing mutation testing tools helps assess the effectiveness of the existing test suite by introducing small changes (mutations) to the code and checking if the tests can detect these changes.
+         This process helps identify gaps in test coverage and ensures that the tests are robust enough to catch potential issues in the code.
+         By integrating mutation testing tools into the development environment, developers can improve their test suites, leading to higher code quality and increased confidence in the software's correctness."
+      }
+    # @sbdl-end
 
   Rule: Fuzz testing
-    amp-devcontainer *MAY* provide fuzz testing tools for the primary programming language(s) used within the container.
-
-    Providing fuzz testing tools helps identify potential security vulnerabilities and robustness issues in the code by automatically generating and executing a large number of random inputs.
-    This process can uncover edge cases and unexpected behaviors that may not be covered by traditional testing methods.
-    By integrating fuzz testing tools into the development environment, developers can improve the overall security and reliability of their software, reducing the risk of vulnerabilities being exploited in production.
+    # @sbdl-begin
+      req-sda-0005 is requirement {
+        custom:title is "[@-LINE]"
+        description is
+        "amp-devcontainer *MAY* provide fuzz testing tools for the primary programming language(s) used within the container."
+        remark is
+        "Providing fuzz testing tools helps identify potential security vulnerabilities and robustness issues in the code by automatically generating and executing a large number of random inputs.
+         This process can uncover edge cases and unexpected behaviors that may not be covered by traditional testing methods.
+         By integrating fuzz testing tools into the development environment, developers can improve the overall security and reliability of their software, reducing the risk of vulnerabilities being exploited in production."
+      }
+    # @sbdl-end

From 9b4e78604cd4cea46935dde7a6bc98887a9a63ea Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Tue, 3 Mar 2026 10:27:07 +0100
Subject: [PATCH 10/11] chore: disable megalinter built-in gherkin-lint

---
 .mega-linter.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.mega-linter.yml b/.mega-linter.yml
index 121ed9cd..48306884 100644
--- a/.mega-linter.yml
+++ b/.mega-linter.yml
@@ -1,7 +1,6 @@
 ENABLE:
   - ACTION
   - DOCKERFILE
-  - GHERKIN
   - JSON
   - MARKDOWN
   - REPOSITORY

From e06a4b7fef4f164f6178c1f75aafc5f25515d836 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Tue, 3 Mar 2026 10:27:28 +0100
Subject: [PATCH 11/11] ci: minor refactor of run steps

---
 .github/workflows/wc-document-generation.yml | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index cf7e0779..fbd37039 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -25,13 +25,9 @@ jobs:
           sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
           python -m pip install gherkin-official==38.0.0 sbdl==1.21.3
       - name: Build & Validate SBDL model
-        run: |
-          set -Eeuo pipefail
-          sbdl -m compile test/cpp/features/*.feature > amp-devcontainer.sbdl
+        run: sbdl -m compile test/cpp/features/*.feature > amp-devcontainer.sbdl
       - name: Generate SRS document
-        run: |
-          set -Eeuo pipefail
-          sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 amp-devcontainer.sbdl > software-requirements-specification.md
+        run: sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 amp-devcontainer.sbdl > software-requirements-specification.md
       - uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
         with:
           args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md