Part II — Requirements¶

GUIDE · PART II — REQUIREMENTS

2.1 Authoring a requirement¶

Every requirement is a .md file. The frontmatter carries the structured attributes; the body carries the prose shall statement and rationale.

---
type: Requirement
id: REQ-SCHED-001
name: "Scheduler shall guarantee priority ordering"
status: approved
reqDomain: software
asilLevel: D          # or silLevel: 4 for IEC 61508
verificationMethod: test
derivedFromSafetyGoal: Safety::SG-KERNEL-001-SchedulingIntegrity   # parent safety goal, a single reference (not derivedFrom: that is requirement-to-requirement, E105)
tags: [safety, scheduler]
---

The scheduler **shall** select the highest-priority ready thread for execution at every
scheduling point, with no priority inversion in the absence of a deliberate inheritance
mechanism.

<!-- Rationale: ThreadX-like semantics; strictly deterministic for SIL4/ASIL-D. -->

Mandatory fields: type, id, name, status. The body must contain at least one shall — W001 fires if absent.

ID pattern: REQ(-[A-Z0-9]{2,12})*-[0-9]{3,8}. Use next-id to avoid clashes:

syscribe -m model next-id REQ-SCHED
# → REQ-SCHED-002

2.2 Requirement hierarchy and derivation¶

Requirements derive from parents with derivedFrom:. Every leaf (derived) requirement must cite an breakdownAdr: that records why the derivation was made — this is the traceability rationale auditors look for.

SafetyGoal (SG-*)
  └─ derivedFromSafetyGoal → Requirement (REQ-* asilLevel: D)
       └─ derivedFrom → Requirement (REQ-* asilLevel: D, more specific)

Critical rule (E312): a parent requirement (one that has derivedChildren) must not appear in any element's satisfies: list. Assign only the leaf requirements to architecture elements; the parent is covered through its children.

Trace a requirement end-to-end:

syscribe -m model trace REQ-SCHED-001

This shows: parent goals → this requirement → architecture elements that satisfy it → test cases that verify it, with verification results if ingested.

2.3 Status lifecycle¶

Status	Meaning	Use
`draft`	Being written; may change	Work in progress; not in coverage count for approved configs
`review`	Under formal review	Optional intermediate state
`approved`	Baselined; changes need change notice	The normal production state
`implemented`	Code/design done; awaiting test	Optional; useful for gap tracking
`verified`	Test evidence recorded	Set when `who-verifies` is fully covered

Track how many requirements are in each state:

syscribe -m model audit
# Reports: approved 80 / draft 28 / ... per package

2.4 Traceability links: what goes where¶

Link	Direction	Field	Validated?
Requirement → parent requirement or goal	up	`derivedFrom:`	Yes (E/W)
Requirement → architecture element	down	`satisfies:` on the PartDef (`satisfiedBy` is the computed reverse index; writing it has no effect)	Yes
Requirement → safety goal	up	`derivedFromSafetyGoal:`	Yes
Requirement → cybersecurity goal	up	`derivedFromCybersecurityGoal:`	Yes
Test case → requirement	up	`verifies:` on the TestCase	Yes

Coverage gap: W015 fires when a requirement is active in a configuration but no test case runs in that configuration. The matrix shows gaps at a glance:

syscribe -m model matrix --gaps-only

2.5 Integrity levels¶

Use exactly one of: - asilLevel: A | B | C | D — ISO 26262 - silLevel: 1 | 2 | 3 | 4 — IEC 61508 - plLevel: a | b | c | d | e — ISO 13849-1

Never set both asilLevel and silLevel on the same requirement (W006). Integrity levels must propagate down the trace: an element derived (via derivedFromSafetyGoal: / derivedFrom:) from, or satisfying, an element that carries an ASIL/SIL must set one too (E841 / E842 / E843), and a lower level than its source needs a breakdownAdr: justifying the decomposition (W808). The level is authored on each element — it is checked, not inherited automatically.

2.6 Multi-variant products (product line engineering)¶

If your product ships in multiple configurations (e.g., entry-level vs. full-featured, or multiple hardware platforms), use appliesWhen: to gate which requirements apply in which variant:

appliesWhen: Features::MPU_ENABLED

The matrix command then shows coverage per configuration. Requirements inactive in a configuration show — (N/A) and do not contribute to its coverage percentage.