docs: improve per flavor traceability

.github/workflows/build-push-test.yml

@@ -63,6 +63,7 @@ jobs:
     permissions: *build-push-test-permissions
     with:
       acceptance-test-path: ${{ (github.actor != 'dependabot[bot]' && matrix.flavor == 'cpp') && 'test/cpp/features' || '' }}
+      acceptance-test-tag: '@flavor:${{ matrix.flavor }}'
       acceptance-test-devcontainer-file: .devcontainer/${{ matrix.flavor }}-test/devcontainer.json
       base-image: ${{ needs.build-push-test-base.outputs.fully-qualified-image-name }}@${{ needs.build-push-test-base.outputs.digest }}
       build-args: |

.github/workflows/wc-acceptance-test.yml

@@ -4,13 +4,16 @@ name: Acceptance Test
 on:
   workflow_call:
     inputs:
-      image-basename:
+      acceptance-test-path:
+        required: true
+        type: string
+      acceptance-test-tag:
         required: true
         type: string
       devcontainer-file:
         required: true
         type: string
-      acceptance-test-path:
+      image-basename:
         required: true
         type: string
     secrets:
@@ -94,9 +97,18 @@ jobs:
           done
         env:
           GH_TOKEN: ${{ secrets.TEST_GITHUB_TOKEN }}
-      - run: cd "${ACCEPTANCE_TEST_PATH}" && npm test
+      - name: Run matching acceptance scenarios
+        run: |
+          set -Eeuo pipefail
+          if [[ -z "${ACCEPTANCE_TEST_TAG}" ]]; then
+            echo "ACCEPTANCE_TEST_TAG must identify the target flavor." >&2
+            exit 1
+          fi
+          cd "${ACCEPTANCE_TEST_PATH}"
+          npm test
         env:
           ACCEPTANCE_TEST_PATH: ${{ inputs.acceptance-test-path }}
+          ACCEPTANCE_TEST_TAG: ${{ inputs.acceptance-test-tag }}
           GITHUB_USER: ${{ secrets.TEST_GITHUB_USER }}
           GITHUB_PASSWORD: ${{ secrets.TEST_GITHUB_PASSWORD }}
           GITHUB_TOTP_SECRET: ${{ secrets.TEST_GITHUB_TOTP_SECRET }}

.github/workflows/wc-build-push-test.yml

@@ -12,6 +12,10 @@ on:
         description: Path to the Playwright acceptance tests (directory that contains playwright.config.ts).
         required: false
         type: string
+      acceptance-test-tag:
+        description: Playwright-BDD tag expression used to select acceptance scenarios.
+        required: false
+        type: string
       base-image:
         description: >-
           Reference of the image this build is based on (the image the Dockerfile builds FROM).
@@ -197,3 +201,4 @@ jobs:
       image-basename: ${{ needs.build-push.outputs.image-basename }}
       devcontainer-file: ${{ inputs.acceptance-test-devcontainer-file }}
       acceptance-test-path: ${{ inputs.acceptance-test-path }}
+      acceptance-test-tag: ${{ inputs.acceptance-test-tag }}

.github/workflows/wc-document-generation.yml

@@ -27,7 +27,11 @@ jobs:
         with:
           persist-credentials: false
       - name: Build & Validate SBDL model
-        run: sbdl -m compile -r . > amp-devcontainer.sbdl
+        run: |
+          set -Eeuo pipefail
+
+          rm test/docs/workspace/sample.sbdl
+          sbdl -m compile -r . > amp-devcontainer.sbdl
       - name: Create document control context
         env:
           GITHUB_REF_NAME: ${{ github.ref_name }}

docs/adr/0000-record-architecture-decisions.md

@@ -8,7 +8,7 @@
 
 The project makes architectural, process, and supply-chain decisions — such as how packages are pinned or how the threat model is expressed — whose rationale is easily lost over time. Commit messages and pull-request discussions are hard to discover after the fact, yet new contributors and auditors need to understand *why* a decision was made, not only *what* the code does.
 
-The container's own maintainability requirement states that amp-devcontainer *SHOULD* document its architectural decisions (see [test/cpp/features/maintainability.feature](../../test/cpp/features/maintainability.feature)). The project therefore needs a lightweight, durable, and discoverable way to capture significant decisions together with their context and consequences.
+The container's own maintainability requirement states that amp-devcontainer *SHOULD* document its architectural decisions (see [req-maint-0004](../requirements/maintainability.feature)). The project therefore needs a lightweight, durable, and discoverable way to capture significant decisions together with their context and consequences.
 
 ## Decision Drivers
 

test/cpp/features/compilation.feature → docs/requirements/compilation.feature

@@ -36,6 +36,20 @@ Feature: Compilation
       When the selected target is built
       Then the output should contain "Build finished with exit code 0"
 
+  Rule: Compile for ARM Cortex target 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
     # @sbdl-begin
       req-comp-0003 is requirement {

docs/templates/requirements-traceability-matrix.md.j2

@@ -26,7 +26,7 @@ footer-right: "\\thepage \\hspace{1pt} of \\pageref*{lastpage}"
 
 ## Purpose
 
-This document provides a requirements traceability matrix (RTM) for amp-devcontainer. It maps each requirement to its associated verification tests, providing evidence of test coverage across the system.
+This document provides a requirements traceability matrix (RTM) for amp-devcontainer. It maps each requirement to its declared verification tests and their source locations. A trace link does not establish that a test was executed or passed.
 
 ## Abstract
 
@@ -40,18 +40,19 @@ This document is generated from a formal model defined in [sbdl](https://sbdl.de
 The authoritative source of change history is the [Git log](https://github.com/philips-software/amp-devcontainer/commits/) of the source material from which the model is built.
 
 # Traceability Matrix
+
+Requirements and tests are identified by their stable IDs. Full requirement descriptions are listed in the *Software Requirements Specification (SRS)*. Full test descriptions are listed under the corresponding requirement in the *Software Verification Plan (SVP)*.
+
 {%- for id, item in sbdl.items() %}
 {%- if item.type == 'aspect' and 'custom:title' in item %}
 
 ## {{ utils.reencode(utils.strip_gherkin_prefix(item['custom:title'])) }}
 
-| Requirement | Test | Status |
-|-------------|------|--------|
+| Requirement ID | Test ID | Source | Traceability |
+|-------------|------|--------|--------------|
 
 {%- if 'requirement' in item %}
 {%- for req_ref in item.requirement %}
-{%- set req = sbdl[req_ref.identifier] %}
-{%- set req_name = utils.reencode(utils.strip_gherkin_prefix(req['custom:title'])) | trim %}
 
 {%- set ns_tests = namespace(test_list=[]) -%}
 
@@ -67,19 +68,18 @@ The authoritative source of change history is the [Git log](https://github.com/p
 
 {%- if ns_tests.test_list -%}
 {%- for test_id in ns_tests.test_list %}
-{%- set test_name = utils.strip_bats_syntax(sbdl[test_id]['custom:title']) | trim %}
-| {{ utils.display_short(req_name) }} | {{ test_id }}: {{ utils.display_short(test_name) }} | Traced |
+| {{ req_ref.identifier }} | {{ test_id }} | {% if sbdl[test_id].reference is defined and sbdl[test_id].reference %}`{{ sbdl[test_id].reference }}`{% else %}Unavailable{% endif %} | Traced |
 {%- endfor -%}
 {%- else %}
-| {{ utils.display_short(req_name) }} | — | **Not covered** |
+| {{ req_ref.identifier }} | — | — | **Untraced** |
 {%- endif -%}
 
 {%- endfor %}
 {%- endif %}
 {%- endif %}
 {%- endfor %}
 
-# Coverage Summary
+# Declared Traceability Summary
 
 {%- set ns_summary = namespace(total_reqs=0, covered_reqs=0, total_tests=0) -%}
 

docs/templates/software-verification-plan.md.j2

@@ -164,6 +164,7 @@ _Verification activities_
 {%- for test_req_ref in test_elem.requirement if test_req_ref.identifier == req_ref.identifier -%}
 {%- set ns_tests.has_tests = true %}
 - **{{ test_id }}**: {{ utils.reencode(utils.strip_bats_syntax(test_elem['custom:title'])) }}
+  Source: {% if test_elem.reference is defined and test_elem.reference %}`{{ test_elem.reference }}`{% else %}Unavailable{% endif %}
 {%- endfor -%}
 {%- endif -%}
 {%- endif -%}

package.json

@@ -11,7 +11,7 @@
   },
   "scripts": {
     "test": "cd $INIT_CWD && npx bddgen && npx playwright test",
-    "watch:bdd-gen": "cd $INIT_CWD && nodemon -L -w features -w steps -w pages -e feature,ts -x 'npx bddgen'",
+    "watch:bdd-gen": "cd $INIT_CWD && nodemon -L -w ../../../docs/requirements -w steps -w pages -w playwright.config.ts -e feature,ts -x 'npx bddgen'",
     "watch:playwright": "cd $INIT_CWD && playwright test --ui",
     "watch": "cd $INIT_CWD && npm run watch:bdd-gen & npm run watch:playwright"
   }

test/cpp/features/playwright.config.ts

@@ -7,8 +7,10 @@ require('dotenv').config({ path: path.join(__dirname, '..', '..', '..', '.env')
 export const STORAGE_STATE = path.join(__dirname, 'playwright/.auth/user.json');
 
 const testDir = defineBddConfig({
-  features: "*.feature",
+  featuresRoot: path.resolve(__dirname, "../../../docs/requirements"),
+  features: path.join(__dirname, "../../../docs/requirements/*.feature"),
   steps: ["steps/*.ts"],
+  tags: process.env.ACCEPTANCE_TEST_TAG,
 });
 
 export default defineConfig({

test/rust/integration-tests.bats

@@ -26,6 +26,7 @@ teardown() {
 }
 
 @test "valid code input should result in working executable targeting the host architecture" {
+  # @sbdl test-comp-0008 is test { custom:title is [[[[@-LINE]]]]; requirement is req-comp-0001 }
   rustc --out-dir build rust/hello.rs
 
   run build/hello
@@ -34,6 +35,7 @@ teardown() {
 }
 
 @test "using cargo run should result in working executable" {
+  # @sbdl test-comp-0009 is test { custom:title is [[[[@-LINE]]]]; requirement is req-comp-0001 }
   pushd cargo
 
   run cargo run
@@ -44,12 +46,14 @@ teardown() {
 }
 
 @test "invalid code input should result in failing build" {
+  # @sbdl test-comp-0010 is test { custom:title is [[[[@-LINE]]]]; requirement is req-comp-0001 }
   run rustc rust/fail.rs
   assert_failure
   assert_output --partial "error: "
 }
 
 @test "running clippy should result in warning diagnostics" {
+  # @sbdl test-sda-0008 is test { custom:title is [[[[@-LINE]]]]; requirement is req-sda-0002 }
   pushd clippy
 
   run cargo clippy
@@ -60,6 +64,7 @@ teardown() {
 }
 
 @test "running rustfmt should result in re-formatted code" {
+  # @sbdl test-sda-0009 is test { custom:title is [[[[@-LINE]]]]; requirement is req-sda-0001 }
   run rustfmt --color=never --check rust/unformatted.rs
   assert_failure
   assert_output --partial - <<EOF
@@ -73,6 +78,7 @@ EOF
 }
 
 @test "coverage information should be generated when running a testsuite" {
+  # @sbdl test-sda-0010 is test { custom:title is [[[[@-LINE]]]]; requirement is req-sda-0003 }
   pushd test
 
   RUSTFLAGS="-C instrument-coverage" run cargo test
@@ -89,6 +95,7 @@ EOF
 }
 
 @test "mutation testing a test executable should be supported" {
+  # @sbdl test-sda-0011 is test { custom:title is [[[[@-LINE]]]]; requirement is req-sda-0004 }
   pushd test
 
   run cargo mutants