diff --git a/.gitignore b/.gitignore index 2900b6074..da016a386 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,4 @@ __pycache__/ # bug: This file is created in repo root on test discovery. /consumer_test.log +/.clwb diff --git a/docs/internals/extensions/metamodel.md b/docs/internals/extensions/metamodel.md index d846779a8..d6a72770b 100644 --- a/docs/internals/extensions/metamodel.md +++ b/docs/internals/extensions/metamodel.md @@ -44,6 +44,44 @@ extensions = [ ] ``` +## SEooC Traceability and AoU Linking + +### Overview +Safety Element Out of Context (SEooC) development requires comprehensive traceability across three dimensions: +1. **Requirements** (what must be done) +2. **Architecture** (how it's structured) +3. **Verification** (proof it works) + +Assumptions of Use (AoU) are central to this model, as they capture the operational context and constraints that validate the safety case. + +### The Traceability Chain +The `covers` link type establishes the connection between requirements and their operational assumptions: + +``` +Stakeholder Requirement + ↓ satisfies +Feature Requirement + ↓ covers +Assumption of Use (AoU) ← defines operational context & constraints + ↓ (informs architecture) +Component Requirement + ↓ fulfils +Component Architecture + ↓ implements +Source Code + ↓ testlink / source_code_link +Verification Evidence +``` + +### Why AoU Matters +- **Safety context**: AoU captures assumptions that validate the safety chain +- **Integration risk**: External component assumptions must be explicitly covered +- **Traceability**: Links features to the operational context they depend on + +**Process Reference**: [gd_req__req_linkage_aou](https://github.com/eclipse-score/process_description/blob/main/process/process_areas/requirements_engineering/guidance/requirements_process_reqs.rst#gd_req__req_linkage_aou) +- Feature and component requirements SHALL link to AoU via the `covers` link type +- Bi-directional traceability via `covered_by` back-link + ## need types Each type of needs is defined in the `needs_types` section of the `metamodel.yaml` file. Each need type has attributes, links, tags, and other properties that define its structure and behavior within the documentation system. diff --git a/docs/internals/requirements/requirements.rst b/docs/internals/requirements/requirements.rst index dd5d8baa5..c6fd684c9 100644 --- a/docs/internals/requirements/requirements.rst +++ b/docs/internals/requirements/requirements.rst @@ -545,6 +545,39 @@ Versioning .. note:: Certain tool requirements do not have a matching process requirement. +.. tool_req:: Enables needs linking via covers attribute (Requirements to AoU) + :id: tool_req__docs_req_link_covers_aou + :tags: Requirements + :implemented: YES + :version: 1 + :satisfies: gd_req__req_linkage_aou + :parent_covered: YES + :status: valid + + Docs-as-Code shall support the ``covers`` link type to establish traceability between + requirements and their Assumptions of Use (AoU), per SCORE process specification. + + **Purpose**: In SEooC (Safety Element Out of Context) development, AoU capture the + operational context and constraints that validate safety cases. Requirements "cover" + (are bound to) specific assumptions. + + **Allowed connections**: + + .. table:: + :widths: auto + + ================================ ======================================================== + Source Type Link Type Target Type + ================================ ======================================================== + Feature Requirements covers Assumptions of Use (AoU) + Component Requirements covers Assumptions of Use (AoU) + ================================ ======================================================== + + **Traceability chain**: Stakeholder Req → Feature Req → (covers) → AoU → Component Req + + **Process reference**: :need:`gd_req__req_linkage_aou` — Requirements SHALL be linked to AoU + via covers if they already cover these. + .. tool_req:: Safety: enforce safe linking :id: tool_req__docs_common_attr_safety_link_check :tags: Common Attributes diff --git a/src/extensions/score_metamodel/metamodel.yaml b/src/extensions/score_metamodel/metamodel.yaml index a7a28c66a..02d3d8450 100644 --- a/src/extensions/score_metamodel/metamodel.yaml +++ b/src/extensions/score_metamodel/metamodel.yaml @@ -306,6 +306,8 @@ needs_types: valid_until: ^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.(0|[1-9]\d*))?$ optional_links: belongs_to: feat # for evaluation + # req-Id: tool_req__docs_req_link_covers_aou + covers: aou_req tags: - requirement - requirement_excl_process @@ -336,6 +338,9 @@ needs_types: # req-Id: tool_req__docs_req_attr_testcov testcovered: ^(YES|NO)$ hash: ^.*$ + optional_links: + # req-Id: tool_req__docs_req_link_covers_aou + covers: aou_req tags: - requirement - requirement_excl_process @@ -943,6 +948,12 @@ needs_extra_links: incoming: fulfilled by outgoing: fulfils + covers: + incoming: covered by + outgoing: covers + # req-Id: gd_req__req_linkage_aou + # Requirement-to-AoU linking per SCORE process specification + implements: incoming: implemented by outgoing: implements diff --git a/src/extensions/score_metamodel/tests/rst/options/test_options_covers_link.rst b/src/extensions/score_metamodel/tests/rst/options/test_options_covers_link.rst new file mode 100644 index 000000000..811d633a0 --- /dev/null +++ b/src/extensions/score_metamodel/tests/rst/options/test_options_covers_link.rst @@ -0,0 +1,85 @@ +.. + # ******************************************************************************* + # Copyright (c) 2026 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +#CHECK: check_options + +.. Tests that `covers` on feat_req and comp_req only allows aou_req as target. +.. req-Id: tool_req__docs_req_link_covers_aou + +.. aou_req:: AoU target for covers tests + :id: aou_req__covers__target + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + + AoU content used for covers-link validation tests. + + +.. stkh_req:: Parent stakeholder requirement for covers tests + :id: stkh_req__covers__parent + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :rationale: Stakeholder parent rationale for covers-link tests. + + +.. feat_req:: Parent feature requirement for covers tests + :id: feat_req__covers__parent + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: stkh_req__covers__parent + + Parent feature requirement used by covers-link tests. + + +.. Positive Test: feat_req pointing to an aou_req via covers is valid. +#EXPECT-NOT: feat_req__covers__good_1.covers (['aou_req__covers__target']): does not follow pattern `^aou_req__.*$`. + +.. feat_req:: Feature requirement with valid covers link + :id: feat_req__covers__good_1 + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: stkh_req__covers__parent + :covers: aou_req__covers__target + + Valid feat_req that covers an AoU requirement. + + +.. Positive Test: comp_req pointing to an aou_req via covers is valid. +#EXPECT-NOT: comp_req__covers__good_1.covers (['aou_req__covers__target']): does not follow pattern `^aou_req__.*$`. + +.. comp_req:: Component requirement with valid covers link + :id: comp_req__covers__good_1 + :reqtype: Functional + :security: NO + :safety: QM + :status: valid + :satisfies: feat_req__covers__parent + :belongs_to: comp__covers__parent + :covers: aou_req__covers__target + + Valid comp_req that covers an AoU requirement. + + +.. feat:: Feature for covers tests + :id: feat__covers__parent + :security: NO + :safety: QM + :status: valid