docs: strengthen documentation templates for qualification friendliness

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

@@ -134,6 +134,7 @@ jobs:
       runner-labels: ${{ inputs.runner-labels }}
       build-test-runner-labels: ${{ inputs.build-test-runner-labels }}
 
+  # @sbdl test-compat-0001 is test { custom:title is "Docker runtime compatibility"; requirement is req-compat-0001 }
   integration-test-docker:
     name: 🧪
     if: ${{ inputs.integration-test-file }}
@@ -150,6 +151,7 @@ jobs:
       registry: ${{ inputs.registry }}
       test-file: ${{ inputs.integration-test-file }}
 
+  # @sbdl test-compat-0002 is test { custom:title is "Podman runtime compatibility"; requirement is req-compat-0001 }
   integration-test-podman:
     name: 🧪
     if: ${{ inputs.integration-test-file && inputs.integration-test-podman }}

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

@@ -254,6 +254,7 @@ jobs:
           subject-digest: ${{ steps.inspect-manifest.outputs.digest }}
           show-summary: false
           push-to-registry: true
+      # @sbdl test-sec-0001 is test { custom:title is "Verify attestation"; requirement is req-sec-0002 }
       - name: Verify attestation
         run: gh attestation verify --repo "${GH_REPO}" --signer-workflow philips-software/amp-devcontainer/.github/workflows/wc-build-push.yml "oci://${FULLY_QUALIFIED_IMAGE_NAME}@${DIGEST}"
         env:

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

@@ -31,7 +31,7 @@ jobs:
           sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
           python -m pip install sbdl==1.22.7
       - name: Build & Validate SBDL model
-        run: sbdl -m compile test/cpp/integration-tests.bats test/cpp/features/*.feature test/embedded-cpp/integration-tests.bats test/embedded-cpp/features/*.feature > amp-devcontainer.sbdl
+        run: sbdl -m compile -r . > amp-devcontainer.sbdl
       - name: Create document control context
         env:
           GITHUB_REF_NAME: ${{ github.ref_name }}
@@ -54,18 +54,18 @@ jobs:
           SBDL
       - name: 📄 Generate SRS document
         run: sbdl -m template-fill --set-config template_extensions_file docs/templates/jinja-extensions.py --template docs/templates/software-requirements-specification.md.j2 amp-devcontainer.sbdl document-control.sbdl > software-requirements-specification.md
-      - name: 🧪 Generate STP document
-        run: sbdl -m template-fill --set-config template_extensions_file docs/templates/jinja-extensions.py --template docs/templates/software-test-plan.md.j2 amp-devcontainer.sbdl document-control.sbdl > software-test-plan.md
+      - name: 🧪 Generate SVP document
+        run: sbdl -m template-fill --set-config template_extensions_file docs/templates/jinja-extensions.py --template docs/templates/software-verification-plan.md.j2 amp-devcontainer.sbdl document-control.sbdl > software-verification-plan.md
       - name: 🧩 Generate RTM document
         run: sbdl -m template-fill --set-config template_extensions_file docs/templates/jinja-extensions.py --template docs/templates/requirements-traceability-matrix.md.j2 amp-devcontainer.sbdl document-control.sbdl > requirements-traceability-matrix.md
       - name: 📄 Generate SRS PDF
         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
-      - name: 🧪 Generate STP PDF
+      - name: 🧪 Generate SVP PDF
         uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
         with:
-          args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-test-plan.pdf software-test-plan.md
+          args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-verification-plan.pdf software-verification-plan.md
       - name: 🧩 Generate RTM PDF
         uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
         with:

docs/templates/software-requirements-specification.md.j2

@@ -26,35 +26,51 @@ footer-right: "\\thepage \\hspace{1pt} of \\pageref*{lastpage}"
 
 ## Purpose
 
-This document describes the software system requirements for amp-devcontainer.
+This document defines the software system requirements for amp-devcontainer.
+It establishes the functional and non-functional requirements the system shall satisfy and provides the basis for verification, traceability, and change control activities throughout the software lifecycle.
+
+## Abstract
+
+amp-devcontainer is a set of Development Containers ([devcontainers](https://containers.dev/)) tailored towards modern software development.
+
+The containers may be used for both local development and continuous integration workflows.
+
+amp-devcontainer is intended as a general-purpose development environment and is not tied to a specific regulated use case.
+The project follows a "qualification-friendly by design" philosophy, emphasizing reproducibility, transparency, configuration control, traceability, supply-chain security controls, and automated generation of objective verification evidence to support organizations in assessing and qualifying the tool for their intended use.
+
+Objective evidence may include automated verification results, software bills of materials (SBOMs), build provenance, cryptographic attestations, and traceability artifacts generated as part of the software lifecycle.
 
 ## Scope
 
-This document covers the requirements for the amp-devcontainer project: a set of devcontainers tailored towards modern, embedded, software development.
+This document defines requirements for the amp-devcontainer container images, supporting build system, and associated lifecycle controls.
+The requirements defined in this document address the amp-devcontainer project itself and shall not be interpreted as qualification evidence for any specific use of the containers within a regulated software development lifecycle.
 
-The following is in scope:
+The following are in scope:
 
 - Container image flavors for C++ and Rust development
-- Tooling for compilation, debugging, static and dynamic analysis
-- Compatibility with IDEs, container runtimes, and ci/cd systems
-- Security properties of released container images
-- Maintainability of the container images and their build system
+- Compilation, debugging, static analysis, and dynamic analysis tooling provided by the containers
+- Compatibility with supported development environments, container runtimes, and continuous integration systems
+- Security characteristics of released container images and associated supply-chain artifacts
+- Build, release, and maintenance capabilities of the project
 
-The following is out of scope:
+The following are out of scope:
 
-- Application-level software built using the containers
-- Deployment of end-user products
-- Requirements for third-party tools and dependencies included in the containers
+- Application software developed using the containers
+- Validation or qualification of the containers for a specific intended use within a regulated development process
+- Deployment and operation of end-user products
+- Requirements governing third-party tools and dependencies outside of the project's control
 
 ## References
 
-| Identifier | Title                                                                                                                                    |
-|------------|------------------------------------------------------------------------------------------------------------------------------------------|
-| RFC 2119   | [Key words for use in RFCs to Indicate Requirement Levels](https://www.rfc-editor.org/rfc/rfc2119)                                       |
-| OCI        | [Open Container Initiative Image Specification](https://github.com/opencontainers/image-spec/blob/main/spec.md)                          |
-| SLSA       | [Supply-chain Levels for Software Artifacts v1.0](https://slsa.dev/spec/v1.0/levels)                                                     |
-| SemVer     | [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)                                                                         |
-| DevC       | [Development Containers Specification](https://containers.dev/)                                                                           |
+| Identifier | Title                                                                                                           |
+|------------|-----------------------------------------------------------------------------------------------------------------|
+| DevC       | [Development Containers Specification](https://containers.dev/)                                                 |
+| in-toto    | [Supply Chain Integrity Framework](https://in-toto.io/)                                                         |
+| OCI        | [Open Container Initiative Image Specification](https://github.com/opencontainers/image-spec/blob/main/spec.md) |
+| RFC 2119   | [Key words for use in RFCs to Indicate Requirement Levels](https://www.rfc-editor.org/rfc/rfc2119)              |
+| SemVer     | [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)                                                |
+| SLSA       | [Supply-chain Levels for Software Artifacts v1.0](https://slsa.dev/spec/v1.0/levels)                            |
+| SPDX       | [Software Package Data Exchange Specification v2.3](https://spdx.github.io/spdx-spec/v2.3/)                     |
 
 ## Document Control
 
@@ -69,21 +85,21 @@ Changes to requirements are tracked at the individual requirement level through
 
 The key words *MUST*, *MUST NOT*, *REQUIRED*, *SHALL*, *SHALL NOT*, *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *MAY*, and *OPTIONAL* in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
 
-## Abstract
-
-amp-devcontainer is a set of [devcontainers](https://containers.dev/) tailored towards modern, embedded, software development.
-
-The containers may be used both for local development and continuous integration (ci).
-
 ## Terminology and Abbreviations
 
 | Term                        | Description/Definition                                                                                                                                         |
 |-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | ARM                         | A family of RISC architectures for computer processors and micro controllers, formerly an acronym for Advanced RISC Machines and originally Acorn RISC Machine |
+| Attestation                 | Cryptographically signed statement about an artifact                                                                                                           |
 | Continuous Delivery (cd)    | Extends ci by automating the release of validated code, extending test automation to ensure that code is production-ready                                      |
 | Continuous Integration (ci) | The practice of continuously integrating developers' work to a shared code-base; including automation for build and test                                       |
 | ELF                         | Executable and Linkable Format, formerly named Extensible Linking Format                                                                                       |
+| OCI                         | Open Container Initiative                                                                                                                                      |
+| Provenance                  | Verifiable metadata describing how a software artifact was built                                                                                               |
 | RISC                        | Reduced Instruction Set Computer                                                                                                                               |
+| SBOM                        | Software Bill of Materials                                                                                                                                     |
+| SLSA                        | Supply-chain Levels for Software Artifacts                                                                                                                     |
+| SPDX                        | Software Package Data Exchange                                                                                                                                 |
 
 # Requirements
 
@@ -100,8 +116,12 @@ The containers may be used both for local development and continuous integration
 
 ### {{ req_ref.identifier }}: {{ utils.reencode(utils.strip_gherkin_prefix(req['custom:title'])) }}
 
+_Requirement_
+
 {{ utils.reencode(req.description) }}
 
+_Rationale_
+
 {{ utils.reencode(req.remark) }}
 
 {%- endfor %}