eclipse-score/communication/score-requirements

S-CORE Requirements Skill

Requirements engineering for S-CORE projects using TRLC (Treat Requirements Like Code) and the rules_score Bazel rules. Requirements are written as code, stored next to the source, version-controlled with Git, and validated automatically by Bazel build/test rules.

Source of truth: the ScoreReq model in

`bazel/rules/rules_score/trlc/config/score_requirements_model.rsl`

and the rule macros under bazel/rules/rules_score/private/. A complete, standalone working

example lives in `bazel/rules/rules_score/examples/seooc/`.

When source and documentation disagree, the source wins.

When to use

• Writing .trlc requirement records or .rsl schema extensions
• Wiring assumed_system_requirements, feature_requirements, component_requirements,

or assumptions_of_use Bazel targets

• Establishing or updating traceability (derived_from) with version pinning
• Allocating requirements to components / dependable elements
• Validating requirements with bazel test

Not for

• Architecture diagrams, unit / component / dependable_element structure → score-architecture
• FMEA / FailureMode / RootCauseAssessment / FTA safety analysis → score-safety-analysis
• Test annotation and coverage → score-testing
• End-to-end SEooC assembly / choosing which skill to use → rules-score

Requirement Hierarchy & Traceability

AssumedSystemReq  →  FeatReq  →  CompReq
    (System)        (Feature)   (Component)
         \                          ↑
          \________________________/

Traceability is enforced by the TRLC type system. Version pinning (e.g. @1) means that when a parent requirement's content changes (and its version is bumped), every downstream reference must be explicitly updated — a change is never silently absorbed.

Workflow: author the content first, then wire it

Requirements work has two phases, in order — do not jump straight to TRLC syntax:

Step 1 — Author the requirement (engineering, sometimes collaborative)

Decide what the requirement says and at which level it belongs. This is an engineering decision governed by the definition of the requirements process in `docs/user_guide/requirements.rst` (Writing Good Requirements). Refine top-down: AssumedSystemReq → FeatReq → CompReq.

Collaborate when the level or intent is unclear — do NOT silently invent a requirement.

• If it is ambiguous whether a need is system-, feature-, or component-level, propose a

placement (with rationale) and confirm with the requirements owner.

• If a source statement is vague, unverifiable, or bundles several concerns, **propose a

sharpened, atomic rewrite** and ask before committing to it.

• Confirm the safety (ASIL) level rather than assuming it.

Step 2 — Wire it in TRLC + Bazel (mechanical)

Only once the content and level are agreed, transcribe it into a .trlc record and wire the Bazel target. This is mechanical: pick the matching ScoreReq type, fill the mandatory fields, add version-pinned derived_from, and add the file to the requirement rule's srcs.

Authoring guidance: writing good requirements

Authoritative rules: `requirements_guidelines.md` (applied by the AI quality check) and Writing Good Requirements in the doc above.

Template: subject shall verb [object] [parameter] [condition] — at least one of object/parameter/condition present. E.g. "The component shall detect if a key-value pair got corrupted and set its status to INVALID during every restart."

Quality criteria:

• Unambiguous — one reading; :term: glossary nouns over vague words (fast, as appropriate).
• Verifiable — a test/review can objectively pass/fail it.
• Atomic — one shall; split "and"/"or" and unbounded lists (etc.).
• Consistent — no contradiction with other requirements.
• Complete — subject + verb + ≥1 of object/parameter/condition; fully specifies behaviour

at its own level without pre-empting lower-level detail.

• Necessary — traces to a parent or rationale.

Use shall for obligations (non-normative notes → note, not description). Keep implementation detail out of system/feature reqs — but an intentional design constraint is a legitimate requirement, not a level violation.

Choose the level by scope/observer: AssumedSystemReq = need from outside the SEooC (black box); FeatReq = spans several components on one feature, solution-neutral; CompReq = fully implementable/testable inside one component.

Refinement (`derived_from`): each child is a narrower, consistent refinement; children together must be sufficient to satisfy the parent; inherit the parent's ASIL or justify lowering it; bump version and re-pin children (@1→@2) on any content change.

# Weak — unverifiable, multi-concern, leaks implementation
"The manager should quickly handle values and store them efficiently in a hash map."
# Better — atomic, verifiable, follows the template
"The numeric value manager shall return the most recently stored uint8_t value on every read access."

The ScoreReq Model (source of truth)

The schema is defined once in score_requirements_model.rsl (package ScoreReq). Projects import it — they do not redefine it. Key facts:

Asil enum — only three values

QM   B   D

There is no A or C in the requirements model. Reference as ScoreReq.Asil.QM, ScoreReq.Asil.B, ScoreReq.Asil.D.

Note: dependable_element(integrity_level = ...) in Bazel accepts A/B/C/D for the

element hierarchy, but requirement records themselves only use QM/B/D.

Field inheritance

Requirement          → description (Markup_String), version (Integer),
                        note (optional String), status (frozen = valid)
  RequirementSafety   → + safety (Asil)
    AssumedSystemReq  → + rationale (String)
    FeatReq           → + derived_from (AssumedSystemReqId[1..*])
    CompReq           → + derived_from (CompReqSourceId[1..*])   # FeatReq, AssumedSystemReq, received AoU, or RootCause (control measure)

• description is a Markup_String — it may contain :term: references and embedded

directives (see Images & diagrams below).

• status is frozen to valid — do not set it.
• note is optional and non-normative.
• The model does not enforce a "shall/should" keyword check (unlike some downstream

projects). Still, write requirements with "shall" for clarity.

• FeatReq and CompReq must not have a lower safety than any upstream requirement

in derived_from (QM < B < D); trlc --verify fails otherwise.

Versioned reference tuples

AssumedSystemReqId, FeatReqId, CompReqSourceId, CompReqId all use the form Package.RecordId@version, e.g. SampleSEooC.ASR_SAMPLE_001@1.

Writing Requirements

Package names are project-specific (e.g. SampleSEooC, SampleComponent). Every file declares its package and imports ScoreReq (plus any package it cross-references).

AssumedSystemReq

package SampleSEooC
import ScoreReq
 
ScoreReq.AssumedSystemReq ASR_SAMPLE_001 {
    description = "The system shall provide safe and reliable numeric value management, compliant with the selected :term:`integrity level`."
    safety = ScoreReq.Asil.B
    version = 1
    rationale = "System-level requirement for managing numeric values in a safety-critical context"
}

Required: description, safety, version, rationale.

FeatReq

package SampleSEooC
import ScoreReq
 
ScoreReq.FeatReq FEAT_001 {
    description = "The :term:`component` shall provide a numeric value management interface that returns a uint8_t value on every read access."
    safety = ScoreReq.Asil.B
    derived_from = [SampleSEooC.ASR_SAMPLE_001@1]
    version = 1
}

Required: description, safety, version, derived_from (≥1 version-pinned AssumedSystemReq).

CompReq

derived_from uses the versioned tuple syntax [Package.RecordId@version] and may reference more than one parent (a FeatReq or an AssumedSystemReq).

package SampleComponent
import ScoreReq
import SampleSEooC
 
ScoreReq.CompReq REQ_COMP_001 {
    description = "The numeric value management interface shall provide a read operation that returns a uint8_t value"
    safety = ScoreReq.Asil.B
    derived_from = [SampleSEooC.FEAT_001@1]
    version = 1
}
 
ScoreReq.CompReq REQ_COMP_004 {
    description = "The numeric value validator shall accept a numeric value manager instance as its sole constructor argument"
    safety = ScoreReq.Asil.B
    derived_from = [SampleSEooC.FEAT_003@1, SampleSEooC.FEAT_004@1]
    version = 1
}

Required: description, safety, version. derived_from is optional — omit it only for component-internal requirements with no feature-level parent.

Assumptions of Use (AoU)

AoU captures a condition the integrating project must satisfy. It has no root-cause field: a RootCauseAssessment of the safety_analysis lists it, with its version, as a measure. The assumptions_of_use rule takes .trlc files, or rst_to_trlc targets converting .rst files carrying aou_req directives. Pass the target as safety_measures to safety_analysis: that makes it an own AoU of the dependable_element (there is no AoU attribute on the element). Forwarding YAML entries name received AoUs with their version (Package.Name@1).

Bazel Rules

Load from the aggregator:

load(
    "@score_tooling//bazel/rules/rules_score:rules_score.bzl",
    "assumed_system_requirements",
    "feature_requirements",
    "component_requirements",
    "assumptions_of_use",
)

Each requirement rule takes name, srcs (the .trlc files, or rst_to_trlc targets converting .rst sources; ref_package of rst_to_trlc names the package that satisfies/derived_from resolve in), and deps (other requirement targets whose records are cross-referenced). All three share the same optional attributes: spec (defaults to the ScoreReq model — override only for a custom schema), lobster_config, and image_srcs.

# docs/requirements/BUILD
 
assumed_system_requirements(
    name = "assumed_system_requirements",
    srcs = ["assumed_system_requirements.trlc"],
    visibility = ["//visibility:public"],
)
 
feature_requirements(
    name = "feature_requirements",
    srcs = ["feature_requirements.trlc"],
    deps = [":assumed_system_requirements"],   # resolve derived_from refs
    visibility = ["//visibility:public"],
)
 
component_requirements(
    name = "component_requirements",
    srcs = ["component_requirements.trlc"],
    deps = [
        ":assumed_system_requirements",
        ":feature_requirements",
    ],
    visibility = ["//visibility:public"],
)